工作流程圖
主賬戶
收款人和支付(創建新的收款人時)
收款人和支付
使用已存在的收款人時
子賬戶(代表)
收款人和支付 - 代表(創建新的收款人時)
收款人和支付 - 代表(使用已存在的收款人時)
集成指南
支付是指從付款人賬戶向收款人轉賬。
不能以一種貨幣付款而以另一種貨幣收款。若要以特定貨幣向收款人支付,付款人必須持有相應貨幣的資金。如有必要,付款人必須在支付前將資金從一種貨幣兌換成另一種貨幣。
在本指南中,您將:
- 查看您持有多少各類外幣。
- 使用您歐元餘額中的資金向德國的收款人支付歐元。
第 1 步:登入
請參閱身份驗證指南,以獲取有關啟動新 API 會話的說明。
第 2 步:查看可用餘額
若要查找您持有多少歐元,請調用獲取餘額 /v2/balances/{currency} 端點,傳遞 EUR
作為第三個 URI 路徑參數。
GET /v2/balances/EUR X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2
以下回應顯示您的 Currencycloud 主賬戶中持有 15,458.12 歐元。
HTTP/1.1 200 OK Content-Type: application/json { "id": "ad6411db-1e00-44fd-b4e8-194c74cf2f83", "account_id": "d22073a6-4c56-4980-8699-504b0c70003f", "currency":"EUR", "amount":"15458.12", "created_at":"2021-12-10T16:05:20+00:00", "updated_at":"2021-12-10T16:05:20+00:00" }
另外,您也可以透過調用查找餘額 /v2/balances/find 端點來查看您 Currencycloud 賬戶中持有的所有外幣餘額。
GET /v2/balances/find X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2
以下回應顯示您的 Currencycloud 主賬戶中持有 10,750.00 英鎊、1,500.24 美元和 15,458.12 歐元。
{ "balances": [ { "id": "c52128a4-3918-40dc-a92a-7225cef3a4a6", "account_id": "d22073a6-4c56-4980-8699-504b0c70003f", "currency":"GBP", "amount":"10750.00", "created_at":"2021-12-10T16:05:19+00:00", "updated_at":"2021-12-10T16:05:19+00:00" }, { "id":"349a2b87-9455-4808-9e68-515daf1f7298", "account_id": "d22073a6-4c56-4980-8699-504b0c70003f", "currency":"USD", "amount":"1550.24", "created_at":"2021-12-10T16:05:19+00:00", "updated_at":"2021-12-10T16:05:19+00:00" }, { "id": "ad6411db-1e00-44fd-b4e8-194c74cf2f83", "account_id": "d22073a6-4c56-4980-8699-504b0c70003f", "currency":"EUR", "amount":"15458.12", "created_at":"2021-12-10T16:05:20+00:00", "updated_at":"2021-12-10T16:05:20+00:00" } ], "pagination": { "total_entries":3, "total_pages":1, "current_page":1, "per_page":25, "previous_page": -1, "next_page": -1, "order": "created_at", "order_asc_desc": "asc" } }
第 3 步:查看支付要求
Currencycloud 支援兩種支付方式:
- 常規(本地)支付:使用本地銀行網絡支付。收款人通常會在結算日後的五個工作天內收到常規支付款項。對於低價值、非緊急的交易來說,這是一個不錯的選擇。
- 優先 (Swift) 支付:使用 Swift 網絡支付。可向超過 212 個國家/地區支付,95% 的支付可於一個工作天內到賬。
舉例來說,假設您需要向位於德國的供應商進行常規(本地)支付。您的歐元餘額中的資金足以進行支付,因此無需事先充值您的歐元餘額。
首先,查看以歐元向在德國開有銀行賬戶的收款人進行常規(本地)支付需要哪些詳細資料。為此,可調用獲取收款人要求 /v2/reference/beneficiary_required_details 端點。
GET /v2/reference/beneficiary_required_details
参数名称 | 参数类型 | 示例值 |
---|---|---|
currency |
Query String | EUR |
bank_account_country |
Query String | DE |
X-Auth-Token |
Header | ea6d13c7bc50feb46cf978d137bc01a2 |
以下回應告訴我們,若要以歐元向德國銀行賬戶進行常規支付,我們需要兩項資料:收款人的 IBAN 和 BIC/Swift 號碼。收款人可以是公司,也可以是個人。無論哪種都需要相同的資料。
HTTP/1.1 200 OK Content-Type: application/json { "details": [ { "payment_type": "priority", "beneficiary_entity_type": "individual", "beneficiary_address": "^.{1,255}", "beneficiary_city": "^.{1,255}", "beneficiary_country": "^[A-z]{2}$", "beneficiary_first_name": "^.{1,255}", "beneficiary_last_name": "^.{1,255}", "iban": "([A-Z0-9]\\s*){15,34}", "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$" }, { "payment_type": "priority", "beneficiary_entity_type": "company", "beneficiary_address": "^.{1,255}", "beneficiary_city": "^.{1,255}", "beneficiary_country": "^[A-z]{2}$", "beneficiary_company_name": "^.{1,255}", "iban": "([A-Z0-9]\\s*){15,34}", "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$" }, { "payment_type": "regular", "iban": "([A-Z0-9]\\s*){15,34}", "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$", "beneficiary_entity_type": "individual" }, { "payment_type": "regular", "iban": "([A-Z0-9]\\s*){15,34}", "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$", "beneficiary_entity_type": "company" } ] }
第 4 步:添加收款人
如果您是與 The Currency Cloud Limited 訂立合約的「贊助」或「財務管理」服務模式下的客戶,則您必須在創建收款人之前驗證收款人的賬戶詳細資料。
如果您知道所需的詳細資料,就可以繼續透過創建收款人 /v2/beneficiaries/create 端點為收款人創建記錄。
POST /v2/beneficiaries/create Content-Type: multipart/form-data
如果收款人已成功創建,則回應訊息將包含您 Currencycloud 賬戶中記錄的收款人完整詳細資料。請記錄收款人的唯一 ID (id
)。下一步向收款人支付時您需要此 ID。
HTTP/1.1 200 OK Content-Type: application/json { "id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b", "bank_account_holder_name":"Acme GmbH", "name":"Acme GmbH", "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 Plc", "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":"1993263d-be07-42d4-b75b-ae4ea18bcb6c", "bank_address": [], "created_at":"2021-02-02T11:52:23+00:00", "updated_at":"2021-02-02T11:52:23+00:00", "beneficiary_external_reference": null }
第 5 步:進行支付
透過調用創建支付 /v2/payments/create 端點來授權支付。您可以選擇(透過 unique_request_id
參數)提供冪等性密鑰。這有助於防止意外的重複支付。
POST /v2/payments/create\ Content-Type: multipart/form-data
參數名稱 | 參數類型 | 示例值 |
---|---|---|
currency |
表單資料 | EUR |
beneficiary_id |
表單資料 | aea097c2-39e4-49b5-aaa6-c860ca55ca0b |
amount |
表單資料 | 10000 |
reason |
表單資料 | 發票支付 |
payment_type |
表單資料 | 常規 |
reference |
表單資料 | 2021-014 |
unique_request_id |
表單資料 | 4abd730f-bb50-4b4a-8890-f46addff222b |
X-Auth-Token |
標頭 | ea6d13c7bc50feb46cf978d137bc01a2 |
如果支付成功排隊,回應有效負載將包含您 Currencycloud 賬戶中記錄的所有支付資訊。這並非表示支付已完成,只是表示已準備好進行處理。
HTTP/1.1 200 OK Content-Type: application/json { "id": "bea05ec4-8c6b-4ec9-80e5-65c0cd257473", "amount":"10000.00", "beneficiary_id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b", "currency":"EUR", "reference":"2021-014", "reason":"Invoice Payment", "status": "ready_to_send", "creator_contact_id":"1993263d-be07-42d4-b75b-ae4ea18bcb6c", "payment_type": "regular", "payment_date":"2021-02-02", "transferred_at": "", "authorisation_steps_required":"0", "last_updater_contact_id":"1993263d-be07-42d4-b-b-ae4ea18bcb6c", "short_reference":"180202-RDRWGQ001", "conversion_id": null, "failure_reason": "", "payer_id":"49d44eff-af91-45b0-a32e-84c7c1750ca0", "payer_details_source": "account", "created_at":"2021-02-02T11:56:05+00:00", "updated_at":"2021-02-02T11:56:05+00:00", "payment_group_id": null, "unique_request_id":"4abd730f-bb50-4b4a-8890-f46addff222b", "failure_returned_amount":"0.00", "ultimate_beneficiary_name": null }
支付採用先進先出的處理方式。Currencycloud 會在指定 payment_date
處理支付,前提是您當時持有足夠的相關貨幣資金。
一旦支付被釋放,收款人就會被複製,而複製版本會變成唯讀。有關更多資訊,請參閱我們的保存收款人詳細資料文章。