This page contains example API calls for providers that have specific requirements.

Bank payments via SWIFT provider

The below are the generic set of fields expected to be used for SWIFT bank payments, including all mandatory fields. There are additional fields which may be used; see API reference for a complete list, and Provider Guide for specific information on using the SWIFT provider.

Some markets may require fields in addition to the below. For more information, contact your representative.

/api/pay sample payload:

{
  "clientId": "a-client",
  "requestId": "769b870d-5031-4121-98f1-b86b4985037b",
  "batchReference": "batch-12345",
   "transactions": [
    {
      "transactionId": "id-12345",
      "provider": "swift",
      "amount": 1,
      "currency": "EUR",
      "recipientAccountId": "NL39RABO1782371249",
      "name": "Jane Doe",
      "address": "Agnietenstraat 1",
      "address2" : "Haidian District",
      "city": "Utrecht",
      "postalCode": "3512",
      "country": "NL",
      "reason": "Payment for goods and services",
      "recipientBank": {
        "bic": "RABONL2U",
      }, 
      "sender": {
          ...
      },
      "intermediary":{
          ...
      },
      "benIntermediaryAgent": {
          ...
      }
    }
  ]
}
  ]
}

/api/pay sample callback:

{
  "clientId": "a-client",
  "requestId": "769b870d-5031-4121-98f1-b86b4985037c",
  "transactions": [
    {
      "transactionId": "id-12345",
      "statusCode": 200,
      "statusDescription": "Succeeded with provider transaction ID ABCDEFG",
      "provider": "swift",
      "walletUpdate": {
        "walletId": "wallet-id",
        "walletCurrency": "EUR",
        "startingCurrentBalance": 100,
        "endingCurrentBalance": 99
      },
      "providerTransactionId": "ABCDEFG",
      "amountPaid": 1,
      "currency": "EUR",
      "feePaid": 0,
      "feeCurrency": "EUR",
      "datePaid": "2022-10-20T08:55:10.9777Z",
      "paymentValueDate": "2022-10-20",
      "statusType": "succeeded",
      "finished": true,
      "transactionType": "pay"
    }
  ],
  "finished": true
}

Sample callback for a reversed payment:

{
  "clientId": "a-client",
  "requestId": null,
  "timestamp": "2022-10-24T06:00:44.389Z",
  "callbackArgs": null,
  "transactions": [
    {
      "transactionId": "new-transaction-id",
      "statusCode": 200,
      "statusDescription": "The funds have been returned to the wallet.",
      "walletUpdate": { 
        "walletId": "wallet-id",
        "walletCurrency": "EUR",
        "startingCurrentBalance": 99, 
        "endingCurrentBalance": 100
      },
      "transactionIdToReverse": "id-12345",
      "reason": "Beneficiary account frozen",
      "reversedAmount": 1,
      "amountReceived": 1,
      "reversedCurrency": "EUR",
      "reversedTime": "2022-10-24T06:00:41.249Z",
      "statusType": "succeeded",
      "finished": true,
      "transactionType": "reverse",
    }
  ],
  "finished": true
}

---

Cross-currency payments

The below are the generic set of fields expected to be used for cross-currency SWIFT bank payments, including all mandatory fields. Not all the below are mandatory, and there are additional fields which may be used; see API reference for a complete list, and Provider Guide for specific information on using cross-currency payments.

Specifying send-side amount

The below is an example of specifying a payment for 1 USD, in which the recipient will receive an equivalent amount of Euros.

/api/pay sample payload:

{
  "requestId": "769b870d-5031-4121-98f1-b86b4985037b",
  "batchReference": "batch-12345",
  "foreignExchange":{
      "tenor": "SPOT",
   "transactions": [
    {
      "transactionId": "id-12345",
      "provider": "swift",
      "sourceCurrencyAmount": 1,
      "currency": "EUR",
      "sourceCurrency": "USD",
      "recipientAccountId": "NL39RABO1782371249",
      "name": "Jane Doe",
      "address": "Agnietenstraat 1",
      "address2" : "Haidian District",
      "city": "Utrecht",
      "postalCode": "3512",
      "country": "NL",
      "reason": "Payment for goods and services",
      "recipientBank": {
        "bic": "RABONL2U",
      },
      "sender": {
          ...
      },
      "intermediary":{
          ...
      }
    }
  ]
}
  ]
}

Specifying receive-side amount

The below is an example of specifying a payment in which the recipient will receive 1 EUR and the sender would be billed for an equivalent amount of USD.

/api/pay sample payload:

{
  "requestId": "769b870d-5031-4121-98f1-b86b4985037b",
  "batchReference": "batch-12345",
  "foreignExchange":{
      "tenor": "SPOT",
   "transactions": [
    {
      "transactionId": "id-12345",
      "provider": "swift",
      "amount": 1,
      "currency": "EUR",
      "sourceCurrency": "USD",
      "recipientAccountId": "NL39RABO1782371249",
      "name": "Jane Doe",
      "address": "Agnietenstraat 1",
      "address2" : "Haidian District",
      "city": "Utrecht",
      "postalCode": "3512",
      "country": "NL",
      "reason": "Payment for goods and services",
      "recipientBank": {
        "bic": "RABONL2U",
      },
      "sender": {
          ...
      },
      "intermediary":{
          ...
      }
    }
  ]
}
  ]
}

Cross-currency payments: returned payment object

Note that /api/pay callbacks do not presently contain FX details. These should be requested via /api/transactionstatus.

/api/transactionstatus response sample payload:

{
  "requestId": "an-id",
      ...
   },
   "transactions": [
    {
      "transactionId": "id-12345",
      "provider": "swift",
      "amount": 565,
      "currency": "XOF",
      "statusCode": 100,
      "statusDescription": "The gateway has received the transaction.",
      ...,
      "foreignExchange": {    
            "sourceCurrency": "USD",
            "SourceCurrencyAmount": 1,
            "typeOfAmountSpecified": "source",
            "linkedFxTradeDetails": {
                  "fxTradeId": "id-abcdef",
                  "destinationCurrency": "XOF",
                  "destinationCurrencyAmount": 565,  
                  "sourceCurrency": "USD",
                  "sourceCurrencyAmount": 1,
                  "fxRate": 565.0000,
                  "tenor": "SPOT",
                  "fxValueDate": "2021-11-05",
                  "fxTransactionTime": "2021-11-04T14:52:26.418Z"
                }
            }  
      }, 
         }, 
      ...,
      }
  ]
}

Bank payments via ACH provider

The below are the generic set of fields expected to be used for ACH bank payments, including all mandatory fields. Please see Provider Guide for specific information on using the ACH provider.

/api/pay sample payload (bank & branch code)

{
  "clientId": "a-client",
  "requestId": "request-id-12345",
  "transactions": [
    {
      "transactionId": "transaction-id-1234",
      "amount": 1000,
      "currency": "XOF",
      "provider": "bank-ach-xof",
      "recipientBank":
    {
      "bankCode": "CI123",
      "branchCode": "12345"
    },
      "recipientAccountId": "123456758910",
      "address" : "Abidjan",
      "country" : "CI",
      "reason" : "Payment for goods and services",
      "name": "Recipient Name"
    }
  ]
}

/api/pay sample payload (IBAN)

{
  "clientId": "a-client",
  "requestId": "request-id-12345",
  "transactions": [
    {
      "transactionId": "transaction-id-1234",
      "amount": 1000,
      "currency": "XOF",
      "provider": "bank-ach-xof",
      "recipientAccountId": "ML1234567890123456789012",
      "address" : "Abidjan",
      "country" : "CI",
      "reason" : "Payment for goods and services",
      "name": "Recipient Name"
    }
  ]
}

/api/pay sample callback

{
  "transactions": [
    {
      "transactionId": "transaction-id-1234",
      "statusCode": 200,
      "statusDescription": "Succeeded with provider transaction ID 436885871",
      "provider": "bank-ach-xof",
      "walletUpdate": {
        "walletId": "12345678",
        "walletCurrency": "XOF",
        "startingCurrentBalance": 7000,
        "endingCurrentBalance": 6000
      },
      "providerTransactionId": "436885871",
      "amountPaid": 1000,
      "currency": "XOF",
      "datePaid": "2023-08-08T12:01:07.289299Z",
      "statusType": "succeeded",
      "finished": true,
      "transactionType": "pay"
    }
  ],
  "finished": true
}