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:

  1. accountId: source account of transfer
  2. 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 /transfer-reasons/{{country}}

{
  "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": {}
}