POBO SWIFT Payment

📘
A wallet is required to initiate payment on behalf of a customer. See create crypto wallet for more information.

To initiate a pay-on-behalf-of (POBO) SWIFT payment, create an external account for the customer.

Create an external account
Create a POBO SWIFT transfer
Monitor transfer status
Webhooks examples

1. Create an external account

Provide customerId when creating an external account on behalf of a customer.

curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/external-accounts \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
    "customerId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "ABC LTD",
    "phone": "+447934758009", 
    "address": {
      "street1": "1 Main Road",
      "street2": "string",
      "postalCode": "string",
      "city": "string",
      "country": "GB"
    },
    "bankName": "asdsad",
    "bankAddress": {
      "street1": "5 Money Lane",
      "street2": "string",
      "postalCode": "10001",
      "city": "Big City",
      "country": "CN" 
    },
    "swift": {
    	"accountNumber": "string", // optional when beneficiaryIban is provided
      "iban": "string", // optional when beneficiaryAccountNumber is provided
      "bic": "ABC123456"
    }
}
'

Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountNumberLast4": "string",
  "receiverName": "string",
  "accountName": "string",
  "swiftCode": "string", 
  "iban": "string",
  "createdAtUtc": "2025-05-22T18:04:27.272Z"
}

2. Create a SWIFT Transfer

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 multiple files such as invoice, sender's company registration document and other supporting documents.

See API reference.

curl --request POST \
     --url https://api.sandbox.keyrails.com/api/v1/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --header 'Authorization: Bearer {{AccessToken}}' \
     --data '{
  "customerId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source": {
    "currency": "USDC",
    "network": "ethereum",
    "walletId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "destination": {
    "currency": "GBP",
    "externalAccountId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "purposeOfPayment": "PaymentForGoods",
  "receiverAmount": 15000.00, // this is the amount in destination currency
  "memo": "test payment",
  "documents": [
   "data:application/pdf;base64,abdcxxxx",
   "data:application/pdf;base64,abdcxxxx"
  ]
}
'

Response:

{
    "id": "43fba2ee-a0b8-40d4-906b-e1f86c9cb4a3",
    "transactionId": "8d5f9f94-eb7b-4d7f-95e8-f649ad10f4fb",
    "status": "New",
    ...
}

Monitor Transfer Status

See API reference.

curl --request GET \
     --url https://api.sandbox.keyrails.com/api/v1/transactions/{transactionId} \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --header 'Authorization: Bearer {{AccessToken}}' \

Response:

The API responds with a transactionId, which can be used to track the transfer.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "New",
  "trackingStatus": "string",
  "trackingReference": "string",
  "currency": "USD",
  "sourceCurrency": "USD",
  "destinationCurrency": "USD",
  "network": "Sepolia",
  "amount": 0,
  "cryptoAmount": 0,
  "transactionFee": 0,
  "appliedFee": 0,
  "totalAmount": 0,
  "comment": "string",
  "memo": "string",
  "purposeOfPayment": "string",
  "country": "string",
   ...
}

Webhooks Examples

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

Webhook types: Transaction
resourceId: References the transaction ID

Processing:

{
  "tenantId": "2711ad4d-2c6b-4238-9f9d-2381d7a6d214",
  "action": "Create",
  "id": "e95503c4-f8bb-4f6b-89d3-42f10307a6bc",
  "resourceId": "b5787a92-82ba-4f09-bacc-02f57ea601ed",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T13:47:04.7710866Z",
  "changes": {
    "transactionStatus": "Processing"
  }
}

Completed:

{
  "tenantId": "36a6deef-8d5a-4560-b17d-e73f1dd3cd88",
  "action": "Update",
  "id": "4c01fdd9-923d-4ad9-9508-48a39cc85a3b",
  "resourceId": "6470d2bd-89e3-4e10-a3ff-605d820f8da3",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T14:06:04.1804263Z",
  "changes": {
    "transactionStatus": "Completed"
  }
}

Failed:

{
  "tenantId": "36a6deef-8d5a-4560-b17d-e73f1dd3cd88",
  "action": "Update",
  "id": "44110cf3-05c4-4652-b718-fc0d6475453f",
  "resourceId": "6470d2bd-89e3-4e10-a3ff-605d820f8da3",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T14:07:01.6713778Z",
  "changes": {
    "transactionStatus": "Failed"
  }
}