Guides
Start typing to search…

Pay Overseas Suppliers in China

In this guide, we'll explore a scenario where USDC funds are transferred into your Keyrails wallet. Following this, you'll initiate a withdrawal to an external USD account in China via GlobalConnect.

1. Create an external account with the suppliers bank details

See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/external-accounts/global-connect \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
    "beneficiaryAccountNumber": "1234567890", // optional when beneficiaryIban is provided
    "beneficiaryIban": "string", // optional when beneficiaryAccountNumber is provided
    "beneficiaryName": "ACME",
    "beneficiaryAddress": {
      "street1": "1 Main Road",
      "street2": "string",
      "postalCode": "string",
      "city": "string",
      "country": "GB"
    },
    "beneficiaryPhoneNumber": "+447934758009",
    "beneficiaryBankName": "ABC Bank",
    "beneficiaryBic": "ABC123456",
    "beneficiaryBankAddress": {
      "street1": "5 Money Lane",
      "street2": "string",
      "postalCode": "10001",
      "city": "Big City",
      "country": "CN" 
    }
}'

The response payload will include an ID. Make a note of the external account ID, as it will be referenced during payment creation.

2. Upload supporting document on behalf of the sender

To expedite the compliance check procedure, you need to upload documents that support the transaction. For instance, if the payment pertains to a trade, you can upload the corresponding invoice and sender's company registration document.

See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/payment-documents \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --header 'Content-Type: multipart/form-data' \
  --form PaymentDocuments='

3. Create GlobalConnect payment

See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/payments/global-connect \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
    "senderName": "Tobi Jones",  //required
    "senderName": "NG", //required
    "source": {
     "currency" "usdc"
    },
    "destination": {
      "externalAccountId": "f3675f2e-da61-42e9-a9db-eef8bd4fb4e2"
    },
    "amount": 5000,
    "currency": "USD", // or AED
    "memo": "bank reference",
    "documentIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08" // uploaded documentId
    ]
}'

📘

Payment fee quote

For payment fee quotes - use the GlobalConnect payment quote API

Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions.

Webhook types: - Payment Transaction

Processing

{
    "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
    "action": "Create",
    "id": "b351897e-6400-4cc0-bcd4-5c37fcce3ccc",
    "resourceId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
    "resourceType": "Payment",
    "createdAtUtc": "2025-02-07T10:24:15.971167Z",
    "changes": {
      "paymentStatus": "New",
      "paymentType": "SettlementGlobalConnectUsdc",
      "createdAt": "2025-02-07T10:24:15.6483540Z"
    }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Create",
  "id": "c9ea8d0d-1b0b-4765-8965-75a16f01ee69",
  "resourceId": "2e586a64-d728-4f81-a575-358b7912baf4",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T10:24:16.385216Z",
  "changes": {
    "transactionStatus": "Processing",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-07T10:24:15.6483543Z",
    "paymentId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
    "amount": null,
    "cryptoAmount": "1.6",
    "transactionHash": "0x4569153de3f34402202a1f1abea25f50d598e0c24e547857986a40b558efecd8"
  }
}

Completed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "36bc2c92-4636-4390-8169-fa706a725b65",
  "resourceId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T10:29:34.766473Z",
  "changes": {
    "paymentStatus": "Completed",
    "paymentType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-07T10:24:15.6483540Z",
    "updatedAt": "2025-02-07T10:29:34.3667760Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "8223ff32-4874-4377-b3ea-cacc4ebcca6e",
  "resourceId": "2e586a64-d728-4f81-a575-358b7912baf4",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T10:29:34.3742514Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-07T10:24:15.6483540Z",
    "paymentId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
    "amount": null,
    "cryptoAmount": "1.6",
    "updatedAt": "2025-02-07T10:29:34.3667760Z",
    "transactionHash": "0x4569153de3f34402202a1f1abea25f50d598e0c24e547857986a40b558efecd8"
  }
}

Failed

{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Create",
  "id": "0fba0eca-49d9-4dc9-9436-b4ff9ffd7d23",
  "resourceId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
  "resourceType": "Payment",
  "createdAtUtc": "2025-02-07T10:27:26.3328119Z",
  "changes": {
    "paymentStatus": "New",
    "paymentType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-07T10:24:15.6483540Z"
  }
}
{
  "tenantId": "a4fca475-42ff-4f98-8c35-901abb6c0ffe",
  "action": "Update",
  "id": "0aea6e07-739f-41cb-a0a1-356a1a31c917",
  "resourceId": "2e586a64-d728-4f81-a575-358b7912baf4",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-07T10:27:25.9722476Z",
  "changes": {
    "transactionStatus": "Failed",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-07T10:24:15.6483540Z",
    "paymentId": "695d791b-295c-4f11-a5df-a6c8f15ac434",
    "amount": null,
    "cryptoAmount": "1.6",
    "updatedAt": "2025-02-07T10:27:25.9675123Z",
    "transactionHash": "0x4569153de3f34402202a1f1abea25f50d598e0c24e547857986a40b558efecd8"
  }
}

Updated 2 months ago