使用不同貨幣的資金向收款人支付

本指南介紹如何使用不同貨幣進行支付以及如何確保有足夠可用餘額用於支付。

在本指南中，我們將：

1. 查看您的 Currencycloud 賬戶中持有多少各類外幣。
2. 透過交易英鎊來充值您的歐元餘額。
3. 以歐元向德國的收款人進行支付。請注意，此功能僅透過即時 API 提供，而非演示 API。

第 1 步：登入

請參閱身份驗證指南，以獲取有關啟動新 API 會話的說明。

第 2 步：查看可用餘額

若要查找您持有多少歐元，請調用獲取餘額 /v2/balances/{currency} 端點，傳遞 EUR 作為第三個 URI 路徑參數。

GET /v2/balances/EUR

以下回應顯示您的 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

以下回應顯示您的 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"
  }
}

在這種情況下，您沒有足夠可用歐元向德國支付 10,000 歐元。您可以向我們發送額外歐元或從可用英鎊餘額中兌換資金。

第 3 步：充值

透過調用獲取詳細匯率 /v2/rates/detailed 端點，查看使用英鎊餘額中的資金購買 10,000 歐元需要花費多少錢。

GET /v2/rates/detailed

成功後，回應有效負載將包含 Currencycloud 的報價詳細資訊以進行兌換。以下示例顯示，您可以賣出 8,059 英鎊來買入 10,000 美元。此報價有效期至 2021 年 2 月 6 日下午 2 點（UTC 時間）。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "settlement_cut_off_time":"2021-02-06T14:00:00Z",
  "currency_pair":"EURGBP",
  "client_buy_currency":"EUR",
  "client_sell_currency":"GBP",
  "client_buy_amount":"10000.00",
  "client_sell_amount":"8059.00",
  "fixed_side": "buy",
  "client_rate":"0.8059",
  "partner_rate": null,
  "core_rate":"0.8059",
  "deposit_required": false,
  "deposit_amount":"0.0",
  "deposit_currency":"GBP",
  "mid_market_rate":"0.8056"
}

如果您對報價感到滿意，您可以透過調用創建兌換 /v2/conversions/create 端點來授權兌換。

POST /v2/conversions/create
Content-Type: multipart/form-data

成功後，回應訊息的有效負載將包含您 Currencycloud 賬戶中記錄的完整兌換詳細資料。記下唯一的兌換 id（id 欄位），如果您要連結兌換和支付，就會需要它。這意味著在兌換結算之前不會處理支付。如果您取消兌換，支付本身將變為暫停狀態，您必須再次重新創建支付，狀態才會變為 ready_to_send。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id":"4c52215f-ca4b-4dcb-a7ae-36edc4f5db16",
  "settlement_date":"2021-02-06T14:00:00+00:00",
  "conversion_date":"2021-02-06T00:00:00+00:00",
  "short_reference":"20210202-FYYXFH",
  "creator_contact_id":"1993263d-be07-42d4-b75b-ae4ea18bcb6c",
  "account_id": "d22073a6-4c56-4980-8699-504b0c70003f",
  "currency_pair":"EURGBP",
  "status": "awaiting_funds",
  "buy_currency":"EUR",
  "sell_currency":"GBP",
  "client_buy_amount":"10000.00",
  "client_sell_amount":"8059.00",
  "fixed_side": "buy",
  "core_rate":"0.8059",
  "partner_rate": "",
  "partner_status": "funds_arrived",
  "partner_buy_amount":"0.00",
  "partner_sell_amount":"0.00",
  "client_rate":"0.8059",
  "deposit_required": false,
  "deposit_amount":"0.00",
  "deposit_currency": "",
  "deposit_status": "not_required",
  "deposit_required_at": "",
  "payment_ids": [],
  "unallocated_funds":"0.00",
  "unique_request_id": null,
  "created_at":"2021-02-02T11:41:29+00:00",
  "updated_at":"2021-02-02T11:41:29+00:00",
  "mid_market_rate":"0.8056"
}

請注意上方兌換對象中的status欄位。兌換有五種可能的狀態：

• 等待資金 (awaiting_funds)
• 資金已匯出 (funds_sent)
• 資金已到賬 (funds_arrived)
• 交易已結算 (trade_settled)
• 已關閉 (closed)

此兌換目前正在等待資金。

第 4 步：查看支付要求

查看以歐元向在德國開有銀行賬戶的收款人進行常規（本地）支付需要哪些詳細資料。為此，可調用獲取收款人要求 /v2/reference/beneficiary_required_details 端點。

GET /v2/reference/beneficiary_required_details
    

以下回應告訴我們，若要以歐元向德國銀行賬戶進行常規支付，我們需要兩項資料：收款人的 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"
    }
  ]
}
    

第 5 步：添加收款人

如果您是與 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
}
    

第 6 步：進行支付

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

POST /v2/payments/create
Content-Type: multipart/form-data
    

您可以透過傳遞 conversion_id 作為參數，將支付與兌換連結。在這些情況下，在兌換結算之前不會處理/執行支付。如果您取消兌換，支付本身將變為「暫停」狀態，您必須再次重新創建支付，狀態才會變為「ready_to_send」。

如果支付成功排隊，回應有效負載將包含您 Currencycloud 賬戶中記錄的所有支付資訊。這並非表示支付已完成，只是表示已準備好進行處理。

支付為異步處理。Currencycloud 會在指定 payment_date 處理支付，前提是您當時持有足夠的相關貨幣資金。即使您沒有足夠的相關貨幣資金，也可以指示支付。支付將以正常方式排隊，但在您的賬戶餘額充值之前不會處理。

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-b75b-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
}