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:
{
"": "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:
{
"": "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)
{
"": "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)
{
"": "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 000000000",
"provider": "bank-ach-xof",
"walletUpdate": {
"walletId": "12345678",
"walletCurrency": "XOF",
"startingCurrentBalance": 7000,
"endingCurrentBalance": 6000
},
"providerTransactionId": "0000000000",
"amountPaid": 1000,
"currency": "XOF",
"datePaid": "2023-08-08T12:01:07.289299Z",
"statusType": "succeeded",
"finished": true,
"transactionType": "pay"
}
],
"finished": true
}
Querying Transaction History Using Inform API
1) How do I retrieve transaction history data for a specific wallet or group of wallets?
By utilising the transaction status endpoint, you can retrieve transaction and balance history for a wallet or group of wallets, enabling you to reconcile the balance movements across your portfolio of accounts.
To view transaction data for a specific wallet, you will need to make a request to the /api/transactionstatus endpoint and include your clientId, requestId and the walletId (single or multiple ids supported) to view the transaction history.
In order to maximise the utility of the api/transactionstatus endpoint we recommend that you establish a consistent polling schedule. This will ensure that the data received from the endpoint aligns with you reconciliation needs, this could be daily, hourly or at a specific interval.
IMPORTANT: By default the /api/transactionstatus endpoint returns transactions data related to outbound & inbound payment receipts only. To return transaction data relating to FX Settlements in addition to the other transaction types, you will need to add an additional query parameter ‘startTime’ alongside the main request. The ‘startTime’ value must be before the transaction time to receive the required data in the response.
Default response behaviour of the /api/transactionstatus endpoint – listed below is inclusive of outbound & inbound payments and exclusive of FX Settlements
Example /api/transactionstatus endpoint request
{
"clientId":"{{clientId}}",
"requestId":"{{requestId}}",
"walletIds" : ["Swift_GBP"]
}
Example /api/transactionstatus endpoint - outbound payment response
{
"transactions": [
{
"transactionId": "0000000-0000000-0000000-0000000",
"statusCode": 200,
"statusDescription": "Succeeded with provider transaction ID 0000000000",
"provider": "swift",
"walletUpdate": {
"walletId": "GBP",
"walletCurrency": "GBP",
"startingCurrentBalance": 100.00,
"endingCurrentBalance": 99.99
},
"providerTransactionId": "0000000",
"amountPaid": 0.01,
"currency": "GBP",
"feePaid": 0,
"feeCurrency": "GBP",
"datePaid": "2023-07-28T13:26:07.206521Z",
"paymentValueDate": "2023-07-27",
"statusType": "succeeded",
"finished": true,
"transactionType": "pay"
}
],
"finished": true
}
Example/api/transactionstatus endpoint request
{
"clientId":"{{clientId}}",
"requestId":"{{requestId}}",
"walletIds" : ["Swift_GBP"]
}
Example /api/transactionstatus endpoint - Inbound payment response
{
"transactionId": "3242960-2022-06-24T14:47:02Z",
"transactionType": "pay",
"statusCode": 200,
"statusDescription": "Transaction succeeded",
"timestamp": "2022-06-24T14:47:02Z",
"amountReceived": 33.33,
"currency": "GBP",
"isReversal": false,
"exchangeRate": 1,
"orderingCustomer": "TEST Client",
"providerTransactionId": "00000000000",
"transactionAmount": 33.33,
"transactionCurrency": "GBP",
"paymentValueDate": "2022-06-24T00:00:00Z",
"walletUpdate": {
"walletId": "Swift_GBP",
"walletCurrency": "GBP",
"startingCurrentBalance": 6618.29,
"endingCurrentBalance": 6651.62
},
"statusType": "succeeded",
"finished": true
},
2. Retrieving all transaction types for reconciliations.
To return all transaction types including FX settlements (in addition to inbound & outbound payments), you will need to add the startTime parameter that precedes the transaction or transactions that you want to view.
To reconcile transaction line items against your account balance, it will be necessary to sum all amountReceived minus amountPaid for all transaction types that are in status 200 or 314. All other status types do not affect the current balance on your account (available balance may be affected by pending transactions instructed in any channel).
Recommended Request Behaviour – in order to retrieve all transactions types via the /api/transactionstatus endpoint.
Request
{
"clientId":"{{clientId}}",
"requestId":"{{requestId}}",
"walletIds" : ["Swift_GBP"],
"startTime" : "2023-04-27T07:24:24Z"
}
Response
"transactions": [
{
"transactionId": "000000-000000-000000-000000",
"statusCode": 200,
"statusDescription": "Succeeded with provider transaction ID 200000000",
"provider": "swift",
"walletUpdate": {
"walletId": "GBP",
"walletCurrency": "GBP",
"startingCurrentBalance": 100.00,
"endingCurrentBalance": 99.99
},
"providerTransactionId": "0000000000",
"amountPaid": 0.01,
"currency": "GBP",
"feePaid": 0,
"feeCurrency": "GBP",
"datePaid": "2023-07-28T13:26:07.206521Z",
"paymentValueDate": "2023-07-27",
"statusType": "succeeded",
"finished": true,
"transactionType": "pay"
}
],
"finished": true
Querying Balances Using Inform API
By utilising the balance endpoint, you can retrieve balances for all accounts.
Balances endpoint (section for how to query the /api/balance endpoint
Request
{
"clientId":"{{clientId}}",
"requestId":"{{requestId}}",
"walletId" : "swift-ae"
}
Response
{
"clientId": "TEST CLIENT",
"wallets": [
{
"walletId": "swift-ae",
"currency": "AED",
"currentBalance": 100.00,
"availableBalance": 50.00,
"activated": true
}
]
}
Example Inform API Responses
PG Outbound Payment (Pay) - ACH
{
"transactionId": "0000000-000000-000000-000000",
"statusCode": 200,
"statusDescription": "Succeeded with provider transaction ID 000000000",
"provider": "bank-ach-xof",
"walletUpdate": {
"walletId": "swift-xof",
"walletCurrency": "XOF",
"startingCurrentBalance": 96579936,
"endingCurrentBalance": 96578930
},
"providerTransactionId": "000000000",
"amountPaid": 1006,
"currency": "XOF",
"feePaid": 0,
"feeCurrency": "XOF",
"datePaid": "2024-05-31T14:00:07.380749Z",
"finished": true,
"statusType": "succeeded",
"transactionType": "pay"
},
PG Outbound Payment (Pay) - Swift
{
"transactionId": "0000000-0000000-0000-0000-00000000",
"statusCode": 200,
"statusDescription": "Succeeded with provider transaction ID 00000000",
"provider": "swift",
"walletUpdate": {
"walletId": "swift-aud",
"walletCurrency": "AUD",
"startingCurrentBalance": 1476632.91,
"endingCurrentBalance": 1476607.91
},
"providerTransactionId": "0000000",
"amountPaid": 25,
"currency": "AUD",
"feePaid": 0,
"feeCurrency": "AUD",
"datePaid": "2024-06-24T08:26:58.503738Z",
"paymentValueDate": "2024-06-25",
"finished": true,
"statusType": "succeeded",
"transactionType": "pay"
},
FX
{
"transactionId": "5665110-2024-03-28T10:00:22Z",
"transactionType": "fx",
"statusCode": 200,
"statusDescription": "Transaction succeeded",
"timestamp": "2024-03-28T10:00:22Z",
"amountReceived": 800000,
"currency": "XOF",
"isReversal": false,
"providerTransactionId": "00000000001",
"transactionAmount": 800000,
"transactionCurrency": "XOF",
"paymentValueDate": "2024-03-28T00:00:00Z",
"walletUpdate": {
"walletId": "swift-xof",
"walletCurrency": "XOF",
"startingCurrentBalance": 164307072,
"endingCurrentBalance": 165107072
},
"foreignExchange": {
"linkedFxTradeDetails": {
"fxTradeId": "100000000000000"
}
},
"finished": true,
"statusType": "succeeded"
}
Inbound Credits
{
"transactionId": "5776581-2024-07-25T11:40:56Z",
"transactionType": "pay",
"statusCode": 200,
"statusDescription": "Transaction succeeded",
"timestamp": ""2024-07-25T11:40:56Z",
"amountReceived": 9000000,
"currency": "XOF",
"isReversal": false,
"exchangeRate": 1,
"narrative": "PAYMENT",
"providerTransactionId": "000000000",
"transactionAmount": 9000000,
"transactionCurrency": "XOF",
"reason": "PAYMENT",
"paymentValueDate": "2024-07-25T00:00:00Z",
"walletUpdate": {
"walletId": "swift-xof",
"walletCurrency": "XOF",
"startingCurrentBalance": 99464634,
"endingCurrentBalance": 108464634
},
"finished": true,
"statusType": "succeeded"
}
Inbound Credit - Reversal
{
"transactionId": "0000000",
"statusCode": 200,
"statusDescription": "The funds have been returned to the wallet.",
"walletUpdate": {
"walletId": "gbp",
"walletCurrency": "GBP",
"startingCurrentBalance": 37226416.09,
"endingCurrentBalance": 37434040.53
},
"transactionIdToReverse": "00000000000",
"reason": "RTN REF00000000",
"reversedAmount": 207602.44,
"amountReceived": 207602.44,
"reversedCurrency": "GBP",
"reversedTime": "2024-02-21T14:06:19.79942Z",
"transactionType": "reverse",
"finished": true,
"statusType": "succeeded"
},