Incoming Transfers
Incoming transfers to all accounts are created as provisioned account credits, then matched with an account and also created as an incoming transfer record. This process is handled by IF when integration is also managed by IF. In this case you can skip Provisioned Account Credit APIs below and check Incoming Transfer APIs. If you have a custom bank connection where the integration is handled by your system, you can reflect incoming transfers to IF system using Provisioned Account Credit APIs below.
Create a Provisioned Account Credit
The first step of creating an incoming transfer is creating a provisioned account credit entity.
Creation of provisioned account credit starts to process of creating an incoming transfer to top up the balance of the account.
POST /provisioned-account-credits
Sample Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"provisionedAccountCredit": {
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"amount": 15,
"currency": "EUR",
"scope": "external",
"scheme": "sepa",
"senderBankAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"senderName": "I.F. TECHNOLOGY",
"senderAddress": "",
"senderToReceiverInformation": "sender to receiver information",
"serviceProviderId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
Sample Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"provisionedAccountCredit": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"amount": 15,
"currency": "EUR",
"scope": "external",
"scheme": "sepa",
"senderBankAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890124",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"senderName": "I.F. TECHNOLOGY",
"senderAddress": "",
"senderToReceiverInformation": "",
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB21",
"sort-code": "000000"
}
},
"serviceProvider": "currency-cloud",
"serviceProviderId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
Get a Provisioned Account Credit
GET /provisioned-account-credits/{id}
Supported path variable:
id:
ID of provisioned account credit in UUID format
Response
{
"workflow": {},
"data": {
"provisionedAccountCredit": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"amount": 15,
"currency": "EUR",
"scope": "external",
"scheme": "sepa",
"senderBankAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890124",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"senderName": "I.F. TECHNOLOGY",
"senderAddress": "",
"senderToReceiverInformation": "",
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB21",
"sort-code": "000000"
}
},
"serviceProvider": "currency-cloud",
"serviceProviderId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
List Provisioned Account Credits
GET /provisioned-account-credits
Request supports these query parameters:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.provisionedAccountCredit.accountId | any particular account id as UUID |
| data.provisionedAccountCredit.currency | currency of account as String |
| data.provisionedAccountCredit.amountFrom | the lowest amount to filter |
| data.provisionedAccountCredit.amountTo | the highest amount to filter |
Response
{
"workflow": {},
"data": {
"provisionedAccountCredits": [
{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"amount": 15,
"currency": "EUR",
"scope": "external",
"scheme": "sepa",
"senderBankAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890124",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"senderName": "I.F. TECHNOLOGY",
"senderAddress": "",
"senderToReceiverInformation": "",
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB21",
"sort-code": "000000"
}
},
"serviceProvider": "currency-cloud",
"serviceProviderId": "00000000-0000-0000-0000-000000000000"
},
{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"amount": 15,
"currency": "EUR",
"scope": "external",
"scheme": "sepa",
"senderBankAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890124",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"senderName": "I.F. TECHNOLOGY",
"senderAddress": "",
"senderToReceiverInformation": "",
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB21",
"sort-code": "000000"
}
},
"serviceProvider": "currency-cloud",
"serviceProviderId": "00000000-0000-0000-0000-000000000000"
}
]
},
"connect": {},
"metadata": {}
}
Incoming Transfers
Incoming transfers are the transactions that increase the balance of the related account.
There are two types of incoming transfers. scope field reflects these types:
1. Internal transfers: You can create internal transfers between all of your clients. When an internal outgoing transfer is created, IF Platform creates an incoming transfer on the receiver account automatically. outgoingTransferId reflects the transaction that created this incoming transfer.
2. External transfers: External transfers are the transactions received from service providers. The scheme field includes the payment scheme used for external transfers.
Relation with an Outgoing Transfer:
Below diagram explains when outgoingTransferId of an incoming transfer will be present to expose the relationship between them.
Get Incoming Transfer
GET /incoming-transfers/{id}
Supported path variable:
id:
ID of incoming transfer in UUID format
Sample Response #1 :
{
"workflow": {},
"data": {
"incomingTransfer":{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "completed",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"transferDate": "2021-04-25",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"incomingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20240207-3QXMN7",
"status": "pending",
"currency": "GBP",
"amount": 675.00,
"feeAmount": 10.00,
"feeCurrency": "GBP",
"outgoingTransferId": "00000000-0000-0000-0000-000000000000",
"serviceProviderId": "00000000-0000-0000-0000-000000000000",
"serviceProviderReference": "BeneficiaryTest",
"senderInformation": null,
"senderName": "Serkan Akagunduz",
"transferDate": null,
"totalAmount": 665.00,
"provisionedAccountCreditId": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "currencycloud",
"receiverAccount": {
"accountHolderName": "Demo Company 005",
"alias": "Joint Account with Amar",
"country": "GB",
"currency": "GBP",
"routingCodes": {},
"accountNumber": null,
"iban": null,
"ledgerNumber": "41735154"
},
"senderAccount": {
"accountHolderName": "Serkan Akagunduz",
"alias": "Serkan Akagunduz GBP",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"sort-code": "040720"
},
"accountNumber": "00000718",
"iban": null,
"ledgerNumber": null
},
"scope": "external",
"scheme": null
}
},
"connect": {},
"metadata": {}
}
Sample Response #2:
{
"timestamp": "2022-04-08T13:50:49.211369",
"message": "A valid incoming transfer record cannot be found with parameters (id)=(fe5d93ec-6c3c-4bb1-886d-56cffc6c307d).",
"code": "common.coding.internal.record_not_found",
"messageParameters": [
"incoming transfer",
"id",
"fe5d93ec-6c3c-4bb1-886d-56cffc6c307d"
]
}
List Incoming Transfers
GET /incoming-transfers
Supported query parameters:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.incomingTransfer.status | one of pending, on-hold, completed, failed |
| data.incomingTransfer.transactionNumber | unique transaction number |
| data.incomingTransfer.amountFrom | minimum amount |
| data.incomingTransfer.amountTo | maximum amount |
| data.incomingTransfer.currency | ISO 4217 currency code |
| data.incomingTransfer.serviceProvider | |
| data.incomingTransfer.clientId | UUID of client |
| data.incomingTransfer.accountId | UUID of account |
| data.incomingTransfer.senderInformation | free text filled by sender |
| data.incomingTransfer.senderName | name of sender |
| data.incomingTransfer.serviceProviderId | |
| data.incomingTransfer.serviceProviderReference | |
| data.incomingTransfer.transferDateFrom | |
| data.incomingTransfer.transferDateTo |
{
"workflow": {},
"data": {
"incomingTransfers": [{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "completed",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"transferDate": "2021-04-25",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
}]
},
"connect": {},
"metadata": {}
}
Webhooks
Incoming transfer webhooks have "incoming-transfers" in the module field in the webhook container object.
There are a couple of types of webhooks sent for incoming transfers as follows:
- incoming-transfer-pending
- incoming-transfer-compliance-in-review
(only this webhook can have an optional complianceCheck object in payload) - incoming-transfer-completed
- incoming-transfer-failed
It is exposed in the webhook.type field.
{
"webhook": {
"module": "incoming-transfers",
"type": "incoming-transfer-pending"
},
"data": {
"incomingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
}
},
"connect": {},
"metadata": {}
}
{
"webhook": {
"module": "incoming-transfers",
"type": "incoming-transfer-compliance-in-review"
},
"data": {
"incomingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
},
"complianceCheck": {
"status": "in-review",
"procedureResults": {
"transaction-monitoring": {
"result": null
}
}
}
},
"connect": {},
"metadata": {}
}
{
"webhook": {
"module": "incoming-transfers",
"type": "incoming-transfer-completed"
},
"data": {
"incomingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "completed",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"transferDate": "2021-04-25",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
}
},
"connect": {},
"metadata": {}
}
{
"webhook": {
"module": "incoming-transfers",
"type": "incoming-transfer-failed"
},
"data": {
"incomingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"accountId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210101-ABC123",
"status": "failed",
"currency": "GBP",
"amount": 100.00,
"feeAmount": 3.00,
"feeCurrency": "GBP",
"outgoingTransferId": null,
"serviceProvider": "railsbank",
"serviceProviderId": "",
"serviceProviderReference": "",
"senderInformation": null,
"senderName": "",
"scheme": "sepa",
"scope": "external",
"totalAmount": 97.00,
"senderAccount": {
"ledgerNumber": null,
"alias": null,
"accountHolderName": null,
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
},
"receiverAccount": {
"ledgerNumber": "12345678",
"alias": "GBP Account",
"accountHolderName": "",
"accountNumber": "00000000",
"iban": "GB99AAAA01234567890123",
"country": "GB",
"currency": "GBP",
"routingCodes": {
"bic": "AAAAGB22",
"sort-code": "000000"
}
}
}
},
"connect": {},
"metadata": {}
}
Compliance Check
Incoming transfers can have compliance checks. Compliance checks can approve or deny the transaction depending on its result. There are two endpoints for compliance checks of incoming transfers.
Get Compliance Check
GET /incoming-transfers/{id}/compliance-check
Supported path variable:
id:
ID of incoming transfer in UUID format
Sample Response:
The response can have multiple procedureResults depending on configurations. The API supports transaction-monitoring procedures. As a result of the procedureResults, procedures can have these result values below:
Acceptable results of transaction-monitoring:
- all-passed
- soft-stop
- hard-stop
- hard-stop-accepted
- hard-stop-rejected
The status of the compliance check can be changed depending on the summarised result of procedure results. status can have these values below:
- in-review
- approved
- rejected
- skipped
{
"workflow": {},
"data": {
"complianceCheck": {
"status": "approved",
"procedureResults": {
"transaction-monitoring": {
"result": "all-passed"
}
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"complianceCheck": {
"status": "in-review",
"procedureResults": {
"transaction-monitoring": {
"result": null
}
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"complianceCheck": {
"status": "skipped",
"procedureResults": {}
}
},
"connect": {},
"metadata": {}
}
Update Compliance Check
PATCH /incoming-transfers/{id}/compliance-check
There is a single workflow to update compliance checks of incoming transfers.
1. Direct: The direct workflow aims to change the result of procedure. The results can be changed only if the configurations are settled to manage compliance checks externally.
Sample Request and Response:
{
"workflow": {
"code": "direct"
},
"data": {
"complianceCheck": {
"procedureResult": { // single procedure to update
"procedure": "transaction-monitoring",
"result": "hard-stop-rejected"
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "direct"
},
"data": {
"complianceCheck": {
"status": "rejected",
"procedureResults": {
"transaction-monitoring": {
"result": "hard-stop-rejected"
}
}
}
},
"connect": {},
"metadata": {}
}
Updated 2 months ago