Guides
Start typing to search…

GlobalConnect

Keyrails GlobalConnect offers a seamless non-pre-funded international 3rd party payments connectivity across the world.

1. Create an external account

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 documents

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/payment-documents \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --header 'Content-Type: multipart/form-data' \
  --form PaymentDocuments=FileOne \
  --form PaymentDocuments=FileTwo \
  --form PaymentDocuments=FileThree

3. Create GlobalConnect payment

To initiate a payment using POBO Swift, set isPoboSwift=true. For non-POBO Swift payments, set isPoboSwift=false See supported currencies

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 '{
    "isPoboSwift": false, // Set to TRUE for POBO Swift
    "senderName": "Tobi Jones",  //required
    "senderCountry": "NG", //required
    "source": {
     "currency" "usdc"
    },
    "destination": {
      "externalAccountId": "f3675f2e-da61-42e9-a9db-eef8bd4fb4e2"
    },
    "amount": 5000,
    "currency": "USD", 
    "memo": "bank reference",
    "documentIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08" // uploaded documentId,
      "297f6eca-6276-4993-bfeb-53cbbbba6f09" // 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.

To simulate transaction outcomes, add the following values to the memo field:

  • Completed Transaction: Use complete_me
  • Failed Transaction: Use fail_me

Webhook types: - Transaction

Processing

{
  "tenantId": "8eef8aad-2935-4bd1-b5df-901f61d169f2",
  "action": "Create",
  "id": "1ab5abb1-a6c5-4b55-bf88-757e439fcd24",
  "resourceId": "f2858fda-7c45-42ea-aa2f-c749d94a29cf",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-21T11:53:34.5841776Z",
  "changes": {
    "transactionStatus": "Processing",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-21T11:53:34.1289329Z",
    "paymentId": "f7c02a1d-560a-441e-9f73-7508cf489aec"
  }
}

Completed

{
  "tenantId": "8eef8aad-2935-4bd1-b5df-901f61d169f2",
  "action": "Update",
  "id": "ec4edb15-c0c3-4094-b48d-d4a98d2042da",
  "resourceId": "f2858fda-7c45-42ea-aa2f-c749d94a29cf",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-21T13:03:06.8090103Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-21T11:53:34.1289320Z",
    "paymentId": "f7c02a1d-560a-441e-9f73-7508cf489aec",
    "updatedAt": "2025-02-21T13:03:06.8079500Z"
  }
}

Failed

{
  "tenantId": "8eef8aad-2935-4bd1-b5df-901f61d169f2",
  "action": "Update",
  "id": "5fa04ba1-e523-4960-a9b0-ac591e36cad1",
  "resourceId": "3b65b2a1-2be4-406e-80f3-43eb66ee36ba",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-21T13:28:42.0360512Z",
  "changes": {
    "transactionStatus": "Failed",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-21T13:27:51.4294870Z",
    "paymentId": "0914ea65-9e96-4a79-b00c-0b1e198f11c1",
    "amount": null,
    "cryptoAmount": "0.5",
    "updatedAt": "2025-02-21T13:28:42.0338981Z",
    "transactionHash": "0xf346412fc4a106bb95909dd7a7830337fd150ab7688dadae653e36bb203806ed"
  }
}

Cancelled

{
  "tenantId": "8eef8aad-2935-4bd1-b5df-901f61d169f2",
  "action": "Update",
  "id": "9c2f1b4b-d582-4443-886a-f91791a80f04",
  "resourceId": "78b6a657-e9bc-4037-9660-d21c7cda520a",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-02-21T13:33:54.6669795Z",
  "changes": {
    "transactionStatus": "Cancelled",
    "transactionType": "SettlementGlobalConnectUsdc",
    "createdAt": "2025-02-21T13:30:44.4087670Z",
    "paymentId": "5887f104-ab1d-4954-a43a-756adf4ffd1a",
    "amount": null,
    "cryptoAmount": "0.5",
    "updatedAt": "2025-02-21T13:33:54.6654754Z",
    "transactionHash": "0x9af4eab0f085f29100e46775b970295b3031296d2c65ae9800f15161dae87a14"
  }
}

Updated about 1 month ago