Outgoing Transfers
Outgoing Transfers are the transactions that decrease the balance of the related account.
There are two types of outgoing transfers. The transferType field reflects these types:
1. Internal transfers: You can create an internal transfer between IF accounts. When an internal outgoing transfer is created, the IF Platform creates an incoming transfer on the receiver account automatically. incomingTransferId reflects the created incoming transfer.
2. External transfers: External transfers are the transactions submitted to a Service Provider to be sent via an external payment scheme such as SWIFT or SEPA. The transferType field includes the payment scheme for external transfers.
Outgoing Transfer Schemes
Outgoing transfer schemes may vary depending on the account, country and, in some cases, the bank of the beneficiary’s bank account. The IF Platform offers an API to list all available transfer schemes for the given account and country.
GET /accounts/{{accountId}}/outgoing-transfer-schemes/{{destinationCountry}}
There are two path parameters that this endpoint expects:
- accountId: source account of transfer
- destinationCountry: country of the beneficiary bank account
{
"workflow": {},
"data": {
"transferSchemes": [
"faster-payments",
"chaps"
]
},
"connect": {},
"metadata": {}
}
Transfer Reasons
There are predefined reasons by country for outgoing transfers. The ID of a selected reason must be provided on creation. Therefore, there is an endpoint for querying available transfer reasons by country.
GET /accounts/{accountId}/transfer-reasons/{{country}}
{
"workflow": {},
"data": {
"transferReasons": [{
"id": "00000000-0000-0000-0000-000000000000",
"description": "Payment for goods and services"
}]
},
"connect": {},
"metadata": {}
}
GET /transfer-reasons/{{country}} - This endpoint is DEPRECATED
{
"workflow": {},
"data": {
"transferReasons": [{
"id": "00000000-0000-0000-0000-000000000000",
"description": "Payment for goods and services"
}]
},
"connect": {},
"metadata": {}
}
Date Metadata
GET /accounts/{{accountId}}/outgoing-transfer-date-metadata/{{transferScope}}/{{transferScheme}}
Each Outgoing Transfer is created for release first available time/date if there is no predefined scheduling set. This endpoint returns the first available date, cutoff time for that date and unavailable dates. This information can, subsequently on creation, be used to create a scheduled outgoing transfer for a future date.
{
"workflow": {},
"data": {
"nextAvailableDate": "2020-01-01",
"nextCutoffDateTime": "2020-01-01T10:00:00",
"unavailableDates": [
"2020-01-04",
"2020-01-05"
]
},
"connect": {},
"metadata": {}
}
Create Outgoing Transfer
POST /outgoing-transfers
The process of creating an Outgoing Transfer is executed using a single workflow. For simplicity, we have called this the Standard Workflow to create an Outgoing Transfer.
This endpoint can be also called in the ‘dry run’ mode. In the ‘dry run’ mode, a Transfer is not actually created, it is merely validated and the associated fee is calculated. Therefore you can call this endpoint to learn about the effects and to gain certainty before creating the transfer. The dryRun parameter is optional and defaults to false.
The contents of the destination field are polymorphic. It depends on whether the desired transaction is internal or external. Examples for both cases:
"scope": "internal",
"scheme": null,
"destination": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
"scope": "external",
"scheme": "faster-payments",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
}
1. Client Direct: A Transfer is created on the Service Provider that the relevant source account is connected to.
Dry run example:
{
"workflow": {
"code": "client.direct",
"dryRun": true,
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee",
"chargingMethod": "on-source"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"scope": "external",
"scheme": "faster-payments",
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
},
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"schemeAttributes": {
"sender-account-number": "",
"trade-order-id": "",
"trade-time": "",
"trade-currency": "",
"trade-amount": "",
"trade-name": "",
"trade-count": "",
"goods-carrier": "",
"service-detail": "",
"service-time": ""
}
},
"pricing": {
"type": "ratio",
"ratio": "0.05",
"boundaryCurrency": "GBP",
"minimumAmount": 12.00,
"maximumAmount": 100000.00
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct",
"dryRun": true,
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee",
"chargingMethod": "on-source"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"originalTransferDate": "2021-04-19",
"rollCount": 0,
"transferCustomReason": null,
"totalAmount": 112.00,
"ownerType": "client",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct",
"dryRun": true,
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"scope": "external",
"scheme": "faster-payments",
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
},
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
Create Transfer example:
{
"workflow": {
"code": "client.direct",
"dryRun": false,
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee",
"chargingMethod": "on-source"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"scope": "external",
"scheme": "faster-payments",
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
},
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"schemeAttributes": {}
},
"pricing": {
"type": "ratio",
"ratio": "0.05",
"boundaryCurrency": "GBP",
"minimumAmount": 12.00,
"maximumAmount": 100000.00
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct",
"dryRun": false,
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee",
"chargingMethod": "on-source"
}
},
"data": {
"outgoingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210419-000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"originalTransferDate": "2021-04-19",
"cutOffDateTime": "2021-04-19T09:00:00",
"rollCount": 0,
"totalAmount": 112.00,
"ownerType": "client",
"scheme": "sepa",
"scope": "external",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct",
"dryRun": false,
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee",
"chargingMethod": "on-source"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"scope": "internal",
"scheme": null,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
},
"destination": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
},
"pricing": {
"type": "ratio",
"ratio": "0.05",
"boundaryCurrency": "GBP",
"minimumAmount": 12.00,
"maximumAmount": 100000.00
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct",
"dryRun": false,
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"outgoingTransfer": {
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"currency": "GBP",
"amount": 100.00,
"scope": "external",
"scheme": "faster-payments",
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
},
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
Scheme Attribute List:
| Currency | Description | Attribute Key | Validataion |
|---|---|---|---|
| KRW | Remitter bank account number | sender-account-num ber | Required |
| CNY | Trade order id | trade-order-id | Required for CNY, max 32 chars |
| CNY | Trade time | trade-time | Required for CNY, dd/MM/yyyy |
| CNY | Trade currency | trade-currency | Required for CNY, 3 letter currency code |
| CNY | Trade currency | trade-amount | Required for CNY, amount in 2 precision |
| CNY | Trade name | trade-name | Required for CNY, max 128 chars, if transfer reason is "Trade Settlement for Services (CSTRDR)" then there is a list of enumerated values*, otherwise free text |
| CNY | Trade count | trade-count | Required for CNY, number |
| CNY | Goods carrier | goods-carrier | Required for CNY, required only if transfer reason is "Trade Settlement for Goods (CGODDR)", max 64 chars |
| CNY | Service detail | service-detail | Required for CNY, required only if transfer reason is "Trade Settlement for Services (CSTRDR)", max 128 chars |
| CNY | Service time | service-time | Required for CNY, required only if transfer reason is "Trade Settlement for Services (CSTRDR)", max 64 chars |
Update Outgoing Transfer
PATCH /outgoing-transfers/{id}
There is single workflow to update outgoing transfers.
1. Direct: using this workflow, certain editable fields of Transfers can be updated. Currently, only the Status can be updated to cancel transfers.
{
"workflow": {
"code": "client.direct"
},
"data": {
"outgoingTransfer": {
"status": "cancelled"
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "direct",
"dryRun": true
},
"data": {
"outgoingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210419-000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"originalTransferDate": "2021-04-19",
"cutOffDateTime": "2021-04-19T09:00:00",
"rollCount": 0,
"totalAmount": 112.00,
"ownerType": "client",
"scheme": "sepa",
"scope": "external",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
Get an Outgoing Transfer
GET /outgoing-transfers/{id}
{
"workflow": {},
"data": {
"outgoingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210419-000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"originalTransferDate": "2021-04-19",
"cutOffDateTime": "2021-04-19T09:00:00",
"rollCount": 0,
"totalAmount": 112.00,
"ownerType": "client",
"scheme": "sepa",
"scope": "external",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
List Outgoing Transfers
GET/outgoing-transfers
Supported query parameters:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.outgoingTransfer.status | one of pending, processing, released, completed, cancelled, failed |
| data.outgoingTransfer.transactionNumber | unique transaction number |
| data.outgoingTransfer.amountFrom | minimum amount |
| data.outgoingTransfer.amountTo | maximum amount |
| data.outgoingTransfer.currency | ISO 4217 currency code |
| data.outgoingTransfer.clientId | UUID of client |
| data.outgoingTransfer.accountId | UUID of account |
| data.outgoingTransfer.serviceProvider | |
| data.outgoingTransfer.serviceProviderId | |
| data.outgoingTransfer.serviceProviderReference | |
| data.outgoingTransfer.transferDateFrom | minimum transfer date |
| data.outgoingTransfer.transferDateTo | maximum transfer date |
| data.outgoingTransfer.description | free text description |
{
"workflow": {},
"data": {
"outgoingTransfers": [{
"id": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210419-000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"originalTransferDate": "2021-04-19",
"cutOffDateTime": "2021-04-19T09:00:00",
"rollCount": 0,
"totalAmount": 112.00,
"ownerType": "client",
"scheme": "sepa",
"scope": "external",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}]
},
"connect": {},
"metadata": {
"page": {
"size": 20,
"number": 0,
"totalElements": 1,
"totalPages": 1
}
}
}
Webhooks
Outgoing transfer webhooks have "outgoing-transfers" in the module field in the webhook container object.
There are five distinct types of webhook sent for outgoing-transfers:
- outgoing-transfer-processing
- outgoing-transfer-released
- outgoing-transfer-completed
- outgoing-transfer-cancelled
- outgoing-transfer-failed
These types are exposed in the webhook.type field.
{
"webhook": {
"module": "outgoing-transfers",
"type": "outgoing-transfer-completed"
},
"data": {
"outgoingTransfer": {
"id": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210419-000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"transferDate": "2021-04-19",
"status": "pending",
"currency": "GBP",
"amount": 100.00,
"feeCurrency": "GBP",
"feeAmount": 12.00,
"description": "API dryRun",
"transferReasonId": "00000000-0000-0000-0000-000000000000",
"transferCustomReason": null,
"originalTransferDate": "2021-04-19",
"cutOffDateTime": "2021-04-19T09:00:00",
"rollCount": 0,
"totalAmount": 112.00,
"ownerType": "client",
"scheme": "sepa",
"scope": "external",
"destination": {
"type": "beneficiary-bank-account",
"beneficiaryBankAccountId": "00000000-0000-0000-0000-000000000000"
},
"source": {
"type": "client-account",
"accountId": "00000000-0000-0000-0000-000000000000"
}
}
},
"connect": {},
"metadata": {}
}
Updated 5 months ago