此组别内的文章

查看更多

子账户活动 (on_behalf_of)

  • 更新

命名账户，也称为子账户，是代表您终端客户的账户。如果您作为一个受监管实体（如 RFXB、中小企业等）运营，我们预期您会对这些终端客户进行自己的 KYC/尽职调查，并可能需要为每个终端客户设置账户，以便在每个单独的账户中进行收款、付款和兑换活动，并且这些账户可以持有多币种钱包。

如果您作为一个未受监管的实体运营，Currencycloud 将与您的终端客户建立直接关系，并负责您终端客户的入驻/KYC 和子账户的创建，而您也可以使用子账户。

使用子账户时，为了访问和处理子账户上的任何活动，需要创建联系人。创建联系人后，应在子账户级别的交易事件（兑换、支付、交易、搜索）中使用 on_behalf_of 参数。

本手册将涵盖子账户的初始设置，以及受监管实体的基本兑换和支付用例。

前提条件

在访问 Currencycloud 的任何端点之前，您需要先完成身份验证并获得验证令牌。请参阅验证指南，获取开始新 API 会话的说明。

为终端客户建立子账户

第 1 步：创建子账户

一旦您完成对终端客户的 KYC 流程，您需要在 Currencycloud 生态系统中使用 Create Accounts /v2/accounts/create 端点创建子账户。以下是成功请求和响应的示例：

POST /v2/accounts/create

参数名称 参数类型 示例值
account_name 表单数据 Jimmy's Burritos
legal_entity_type 表单数据 company
street 表单数据 123 Main Street
city 表单数据 Denver
country 表单数据 US
postal_code 表单数据 80209
your_reference 表单数据 12345678
status 表单数据 enabled
state_or_province 表单数据 CO
identification_type 表单数据 incorporation_number
identification_value 表单数据 123456789
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

响应：

{
    "id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
    "account_name":"Jimmy's Burritos",
    "brand": "currencycloud",
    "your_reference":"123456789",
    "status": "enabled",
    "street":"123 Main Street",
    "city":"Denver",
    "state_or_province":"CO",
    "country":"US",
    "postal_code":"80209",
    "spread_table": "flat_0.00",
    "legal_entity_type": "company",
    "created_at":"2021-03-25T15:22:47.276+00:00",
    "updated_at":"2021-03-25T15:22:47.275+00:00",
    "identification_type": "incorporation_number",
    "identification_value":"123456789",
    "short_reference":"210325-03783",
    "api_trading": true,
    "online_trading": true,
    "phone_trading": true,
    "process_third_party_funds": false,
    "settlement_type": "net",
    "agent_or_reliance": false,
    "terms_and_conditions_accepted": null
}

从响应负载中，您需要解析并保留 Account UUID，如上例所示的 id 参数。这个值将在下一次 API 调用中使用，用于在此特定子账户上创建联系人。

第 2 步：创建联系人

下一步是使用 Create Contact /v2/contacts/create 端点为您刚创建的子账户创建联系人。为子账户创建的联系人将允许您在子账户级别进行兑换、付款和报告活动。

请注意，login_id 必须是唯一的，如果未指定 login_id，则将使用 email_address。

以下是成功请求和响应负载的示例：

POST /v2/contacts/create

参数名称 参数类型 示例值
account_id 表单数据 53d15949-b1e9-4335-a4e4-56ae8adef95e
first_name 表单数据 Eric
last_name 表单数据 Johnson
email_address 表单数据 eric@aol.com
phone_number 表单数据 99999999
your_reference 表单数据 123456789
status 表单数据 enabled
timezone 表单数据 America/New York
date_of_birth 表单数据 1993-01-01
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

响应：

{
    "login_id": "eric@aol.com",
    "id": "ce404ead-1936-4f54-ac2a-b26ec03d5560",
    "first_name":"Eric",
    "last_name":"Johnson",
    "account_id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
    "account_name":"Jimmy's Burritos",
    "status": "enabled",
    "locale": "en",
    "timezone":"America\/New_York",
    "email_address": "eric@aol.com",
    "mobile_phone_number": null,
    "phone_number":"99999999",
    "your_reference":"123456789",
    "date_of_birth":"1993-01-01",
    "created_at":"2021-03-25T15:45:22.325+00:00",
    "updated_at":"2021-03-25T15:45:22.320+00:00"
}

您需要从上面的示例响应负载中解析并获取 id 参数。该值将用于后续 API 调用中的 on_behalf_of 参数。

代表您的终端客户进行兑换

第 1 步：代表您的终端客户获取报价汇率

这个基本流程假设子账户在多币种账户中持有可用资金。在我们的演示环境中进行测试时，请与您的专门解决方案顾问合作，他们可以帮助您将占位资金存入各个子账户钱包。

让我们通过调用 Get Detailed Rates /v2/rates/detailed 端点，查看使用您终端客户的英镑余额购买 10,000 欧元需要花费多少。

 

GET /v2/rates/detailed

参数名称 参数类型 示例值
buy_currency 查询字符串 EUR
sell_currency 查询字符串 GBP
amount 查询字符串 10000.00
fixed_side 查询字符串 buy
on_behalf_of 查询字符串 ce404ead-1936-4f54-ac2a-b26ec03d5560
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

成功时，响应负载将包含 Currencycloud 报价的详细信息以代表您的终端客户进行兑换。以下示例告诉您，您的终端客户可以出售 £8037.00 以购买 €10,000。请注意，报价汇率仅供参考，必须进行兑换预订以锁定汇率。

{
    "settlement_cut_off_time":"2021-03-29T14:30:00Z",
    "currency_pair":"EURGBP",
    "client_buy_currency":"EUR",
    "client_sell_currency":"GBP",
    "client_buy_amount":"10000.00",
    "client_sell_amount":"8037.00",
    "fixed_side": "buy",
    "client_rate":"0.8037",
    "partner_rate": null,
    "core_rate":"0.8037",
    "deposit_required": false,
    "deposit_amount":"0.0",
    "deposit_currency":"GBP",
    "mid_market_rate":"0.8036"
}

第 2 步：代表您的终端客户进行兑换

如果您和您的终端客户对报价汇率感到满意，您可以调用 Create Conversion /v2/conversions/create 端点为您的终端客户创建兑换。

或者，您可以提供幂等键（通过 unique_request_id 参数）。这有助于防止意外重复兑换。

 

POST /v2/conversions/create

参数名称 参数类型 示例值
buy_currency 表单数据 EUR
sell_currency 表单数据 GBP
amount 表单数据 10000.00
fixed_side 表单数据 buy
reason 表单数据 Top up Euros balance
term_agreement 表单数据 true
on_behalf_of 表单数据 ce404ead-1936-4f54-ac2a-b26ec03d5560
unique_request_id 表单数据 5f022044-1277-4f7e-a68e-c68783647748
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

成功时，响应消息的负载将包含在终端客户的 Currencycloud 命名子账户中记录的完整兑换详情。示例响应：

{
    "id":"0e716494-3688-499a-8391-38096582aad5",
    "settlement_date":"2021-03-29T14:30:00+00:00",
    "conversion_date":"2021-03-29T00:00:00+00:00",
    "short_reference":"20210325-XPWDTQ",
    "creator_contact_id": "ce404ead-1936-4f54-ac2a-b26ec03d5560",
    "account_id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
    "currency_pair":"EURGBP",
    "status": "awaiting_funds",
    "buy_currency":"EUR",
    "sell_currency":"GBP",
    "client_buy_amount":"10000.00",
    "client_sell_amount":"8037.00",
    "fixed_side": "buy",
    "core_rate":"0.8037",
    "partner_rate": "",
    "partner_buy_amount":"0.00",
    "partner_sell_amount":"0.00",
    "client_rate":"0.8037",
    "deposit_required": false,
    "deposit_amount":"0.00",
    "deposit_currency": "",
    "deposit_status": "not_required",
    "deposit_required_at": "",
    "payment_ids": [],
    "unallocated_funds":"10000.00",
    "unique_request_id": null,
    "created_at":"2021-03-25T20:53:47+00:00",
    "updated_at":"2021-03-25T20:53:48+00:00",
    "mid_market_rate":"0.8036"
}

只要子账户的英镑余额足够支付 client_sell_amount，此兑换将在 settlement_date 自动结算。如果需要，请使用您的现金管理器为终端客户的子账户英镑余额充值。

代表您的终端客户发送付款

现在您已将资金兑换为欧元，您可以代表终端客户向收款人进行付款。以下部分将指导您如何在子账户级别添加收款人、查看账户余额并进行付款。

第 1 步：查看可用余额

要了解终端客户的货币钱包中有多少欧元，请调用 Get Balance /v2/balances/{currency} 端点，将 EUR 作为第三个 URI 路径参数传递，并包含 on_behalf_of 作为查询字符串参数。

GET /v2/balances/EUR/?on_behalf_of=ce404ead-1936-4f54-ac2a-b26ec03d5560
X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2

以下响应显示您终端客户的子账户持有 €987,456.00。

响应：

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": "a1c6c7dc-430c-438c-b7e2-60d33b517ab8",
    "account_id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
    "currency":"EUR",
    "amount":"987456.00",
    "created_at":"2021-03-25T21:17:08+00:00",
    "updated_at":"2021-03-25T22:02:57+00:00"
}

或者，您可以调用 Find Balances /v2/balances/find 端点，查看您终端客户持有的所有外币余额。同样，您需要将 on_behalf_of 作为查询字符串参数传递。

GET /v2/balances/find?on_behalf_of=ce404ead-1936-4f54-ac2a-b26ec03d5560
X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2

以下响应显示您的终端客户在其 Currencycloud 子账户中持有 £557,685.00 和 €987,456.00。

{
    "balances": [
        {
            "id": "a1c6c7dc-430c-438c-b7e2-60d33b517ab8",
            "account_id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
            "currency":"EUR",
            "amount":"987456.00",
            "created_at":"2021-03-25T21:17:08+00:00",
            "updated_at":"2021-03-25T22:02:57+00:00"
        },
        {
            "id": "e08bdda0-18b0-4425-aabe-2c3da28cca89",
            "account_id":"53d15949-b1e9-4335-a4e4-56ae8adef95e",
            "currency":"GBP",
            "amount":"557685.00",
            "created_at":"2021-03-25T21:18:22+00:00",
            "updated_at":"2021-03-25T22:02:58+00:00"
        }
    ],
    "pagination": {
        "total_entries":2,
        "total_pages":1,
        "current_page":1,
        "per_page":25,
        "previous_page": -1,
        "next_page": -1,
        "order": "created_at",
        "order_asc_desc": "asc"
    }
}

第 2 步：在子账户级别添加收款人

如果您是赞助或财政服务模型的客户，并与 The Currency Cloud Limited 签订合同，那么您必须先验证收款人的账户详细信息，才能创建收款人。

如果您和您的终端客户已了解所需信息，可以通过 Create Beneficiary /v2/beneficiaries/create 端点创建收款人记录。

POST /v2/beneficiaries/create

如果收款人成功创建，则响应消息将包含在您终端客户的 Currencycloud 子账户中记录的收款人完整详细信息。请注意收款人的唯一 ID (id)。在下一步中，您将需要此 ID 来向收款人支付。

响应：

{
    "id":"33bb1228-20fc-4569-b5b2-234c3fd9e492",
    "bank_account_holder_name":"Joe Bob",
    "name":"Joe Bob",
    "email": null,
    "payment_types": [
        "regular"
    ],
    "beneficiary_address": [],
    "beneficiary_country":"DE",
    "beneficiary_entity_type": null,
    "beneficiary_company_name": null,
    "beneficiary_first_name": null,
    "beneficiary_last_name": null,
    "beneficiary_city": null,
    "beneficiary_postcode": null,
    "beneficiary_state_or_province": null,
    "beneficiary_date_of_birth": null,
    "beneficiary_identification_type": null,
    "beneficiary_identification_value": null,
    "bank_country":"DE",
    "bank_name":"TEST BANK NAME",
    "bank_account_type": null,
    "currency":"EUR",
    "account_number": null,
    "routing_code_type_1": null,
    "routing_code_value_1": null,
    "routing_code_type_2": null,
    "routing_code_value_2": null,
    "bic_swift":"COBADEFF",
    "iban":"DE89370400440532013000",
    "default_beneficiary": "false",
    "creator_contact_id": "ce404ead-1936-4f54-ac2a-b26ec03d5560",
    "bank_address": [
        "TEST BANK ADDRESS",
        " NOT USING EXTERNAL SERVICE",
        " DEVELOPMENT ENVIRONMENT."
    ],
    "created_at":"2021-03-25T22:52:30+00:00",
    "updated_at":"2021-03-25T22:52:30+00:00",
    "beneficiary_external_reference": null
}

第 3 步：代表您的终端客户进行支付

通过调用 Create Payment /v2/payments/create 端点创建支付。或者，您可以提供幂等键（通过 unique_request_id 参数）。这有助于防止意外重复付款。

POST /v2/payments/create

参数名称 参数类型 示例值
currency 表单数据 EUR
beneficiary_id 表单数据 33bb1228-20fc-4569-b5b2-234c3fd9e492
amount 表单数据 10000
reason 表单数据 Invoice Payment
payment_type 表单数据 regular
reference 表单数据 2021-014
on_behalf_of 表单数据 ce404ead-1936-4f54-ac2a-b26ec03d5560
unique_request_id 表单数据 5f022044-1277-4f7e-a68e-c68783647748
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

如果支付成功排入队列，则响应负载将包含在您终端客户的 Currencycloud 子账户中记录的支付完整详细信息。这并不意味着付款已经完成，而是表示付款已准备好进行处理。

响应：

{
    "id":"33efe062-ead2-4781-81a7-72563475603f",
    "amount":"10000.00",
    "beneficiary_id":"33bb1228-20fc-4569-b5b2-234c3fd9e492",
    "currency":"EUR",
    "reference":"2021-014",
    "reason":"Invoice Payment",
    "status": "ready_to_send",
    "creator_contact_id": "ce404ead-1936-4f54-ac2a-b26ec03d5560",
    "payment_type": "regular",
    "payment_date":"2021-03-29",
    "transferred_at": "",
    "authorisation_steps_required":"0",
    "last_updater_contact_id": "ce404ead-1936-4f54-ac2a-b26ec03d5560",
    "short_reference":"210326-0PC0TV750",
    "conversion_id": null,
    "failure_reason": "",
    "payer_id":"45cc568d-a837-4538-b1d8-882a367c8d46",
    "payer_details_source": "account",
    "created_at":"2021-03-26T20:32:59+00:00",
    "updated_at":"2021-03-26T20:32:59+00:00",
    "payment_group_id": null,
    "unique_request_id":"5f022044-1277-4f7e-a68e-c68783647748",
    "failure_returned_amount":"0.00",
    "ultimate_beneficiary_name": null,
    "purpose_code": null,
    "charge_type": null,
    "fee_amount": null,
    "fee_currency": null
}
这篇文章有帮助吗？
1 人中有 1 人觉得有帮助
返回页首

相关文章