此段落內的文章

檢視更多

子賬戶活動 (on_behalf_of)

  • 更新於

指定賬戶也稱為子賬戶，是代表您最終客戶的賬戶。如果您作為受規管的實體（RFXB、MSB 等）營運，我們預期您會對這些客戶執行自己的 KYC/盡職調查，並可能需要為每個客戶開立賬戶，在每個賬戶中進行託收、支付和兌換活動，而且這些賬戶可以持有多幣種錢包。

如果您作為不受規管的實體營運，您也可以使用子賬戶，我們 Currencycloud 與您的最終客戶直接建立關係，並且我們負責註冊/KYC 和子賬戶的創建。

使用子賬戶時，為存取和處理子賬戶上的任何活動，需要創建聯絡人。創建聯絡人後，on_behalf_of 參數應在子賬戶級別的交易事件（兌換、支付、交易、搜索）中使用。

本指南將考慮子賬戶的初始設定，以及受規管實體的基本兌換和支付用例。

先決條件

在存取任何 Currencycloud 端點之前，您需要進行身份驗證並獲取身份驗證令牌。請參閱身份驗證指南，以獲取有關啟動新 API 會話的說明。

為客戶開立子賬戶

第 1 步：創建子賬戶

在完成對最終客戶的 KYC 流程後，您將需要使用創建賬戶 /v2/accounts/create 端點在 Currencycloud 生態系統中創建一個子賬戶。成功請求與回應的示例如下：

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
}

您將需要從回應有效負載中解析並保留上述示例中的賬戶 UUID (id) 參數。該值將用於下一次 API 調用，以在此特定子賬戶上創建聯絡人。

第 2 步：創建聯絡人

下一步是使用創建聯絡人 /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 表單資料 美國/紐約
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 步：代表您的客戶獲取報價

此基本流程假設子賬戶在多幣種賬戶中有可用資金。為了在我們的演示環境中進行測試，請與您的專門解決方案顧問合作，以便他們可以協助您將占位資金存入各個子賬戶錢包。

我們透過調用獲取詳細匯率 /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 步：代表您的客戶進行兌換

如果您和您的客戶都對報價感到滿意，您可以透過調用創建兌換 /v2/conversions/create 端點來為您的客戶創建兌換。

您可以選擇（透過 unique_request_id 參數）提供冪等性密鑰。這有助於防止意外的重複兌換。

 

POST /v2/conversions/create

參數名稱 參數類型 示例值
buy_currency 表單資料 EUR
sell_currency 表單資料 GBP
amount 表單資料 10000.00
fixed_side 表單資料 buy
reason 表單資料 充值歐元餘額
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 步：查看可用餘額

若要查找您客戶的貨幣錢包中有多少歐元，請調用獲取餘額 /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"
}

另外，您也可以透過調用查找餘額 /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 訂立合約的「贊助」或「財務管理」服務模式下的客戶，則您必須在創建收款人之前驗證收款人的賬戶詳細資料。

如果您和您的客戶知道所需的詳細資料，您就可以繼續透過創建收款人 /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 步：代表您的客戶進行支付

透過調用創建支付 /v2/payments/create 端點來創建支付。您可以選擇（透過 unique_request_id 參數）提供冪等性密鑰。這有助於防止意外的重複支付。

POST /v2/payments/create

參數名稱 參數類型 示例值
currency 表單資料 EUR
beneficiary_id 表單資料 33bb1228-20fc-4569-b5b2-234c3fd9e492
amount 表單資料 10000
reason 表單資料 發票支付
payment_type 表單資料 常規
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 人覺得有幫助
返回頂端

相關文章