此组别内的文章

查看更多

使用不同货币资金向收款人支付

  • 更新

本指南解释了如何以不同货币支付，以及如何确保账户中有足够的余额完成付款。

在本指南中，我们将：

  1. 查看您 Currencycloud 账户中持有的各种外币金额。
  2. 通过交易一些英镑来为您的欧元余额充值。
  3. 使用欧元向德国的收款人支付。请注意，此功能仅通过真实 API 提供，不支持演示 API。

第 1 步：登录

请参阅验证指南，获取开始新 API 会话的说明。

第 2 步：查看可用余额

要查看您拥有多少欧元，请调用 Get Balance /v2/balances/{currency} 端点，传入 EUR 作为第三个 URL 路径参数。

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

或者，您可以调用 Find Balances /v2/balances/find 端点，查看您在 Currencycloud 账户中持有的所有外币余额。

GET /v2/balances/find
参数名称 参数类型 示例值
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

以下响应显示您在 Currencycloud 主账户中持有 £10,750.00、US$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 步：充值

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

GET /v2/rates/detailed
参数名称 参数类型 示例值
buy_currency 查询字符串 EUR
sell_currency 查询字符串 GBP
amount 查询字符串 10000.00
fixed_side 查询字符串 buy
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

成功时，响应负载将包含 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"
}

如果您对报价汇率感到满意，可以调用 Create Conversion /v2/conversions/create 端点来授权兑换。

POST /v2/conversions/create
Content-Type: multipart/form-data
参数名称 参数类型 示例值
buy_currency 表单数据 EUR
sell_currency 表单数据 GBP
amount 表单数据 10000.00
fixed_side 表单数据 buy
reason 表单数据 Top up Euros balance
term_agreement 表单数据 true
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

成功时，响应消息的负载将包含在您 Currencycloud 账户中记录的完整兑换详情。请记录唯一的兑换 ID（id 字段），如果您想要将兑换与付款关联，则需要此信息。这意味着在兑换结算之前，支付将不会被处理。如果您取消了兑换，支付状态将会变为 suspended。您需要重新创建支付，才能将状态更改为 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 步：查看支付要求

查看以欧元向在德国拥有银行账户的收款人进行常规（本地）支付需要哪些详细信息。为此，您可以调用 Get Beneficiary Requirements /v2/reference/beneficiary_required_details 端点。

GET /v2/reference/beneficiary_required_details
参数名称 参数类型 示例值
currency 查询字符串 EUR
bank_account_country 查询字符串 DE
X-Auth-Token 标头 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"
    }
  ]
}

第 5 步：添加收款人

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

如果您已了解所需信息，可以通过 Create Beneficiary /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 步：进行支付

通过调用 Create Payment /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 表单数据 Invoice Payment
payment_type 表单数据 regular
reference 表单数据 2021-014
unique_request_id 表单数据 4abd730f-bb50-4b4a-8890-f46addff222b
X-Auth-Token 标头 ea6d13c7bc50feb46cf978d137bc01a2

您可以传递 conversion_id 作为参数，将付款与该兑换关联。在这种情况下，付款将在兑换结算后才会被处理/执行。如果您取消了兑换，支付状态将会变为 "suspended"。您需要重新创建支付，才能将状态更改为 "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
}
这篇文章有帮助吗？
0 人中有 0 人觉得有帮助
返回页首

相关文章