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:

parameterdescription
metadata.page.number0-indexed, default=0
metadata.page.sizedefault=10
data.provisionedAccountCredit.accountIdany particular account id as UUID
data.provisionedAccountCredit.currencycurrency of account as String
data.provisionedAccountCredit.amountFromthe lowest amount to filter
data.provisionedAccountCredit.amountTothe 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:

parameterdescription
metadata.page.number0-indexed, default=0
metadata.page.sizedefault=10
data.incomingTransfer.statusone of pending, on-hold, completed, failed
data.incomingTransfer.transactionNumberunique transaction number
data.incomingTransfer.amountFromminimum amount
data.incomingTransfer.amountTomaximum amount
data.incomingTransfer.currencyISO 4217 currency code
data.incomingTransfer.serviceProvider
data.incomingTransfer.clientIdUUID of client
data.incomingTransfer.accountIdUUID of account
data.incomingTransfer.senderInformationfree text filled by sender
data.incomingTransfer.senderNamename 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": {}
}