Transfers

Overview

The Transfers module of the Customer API facilitates the movement of funds and manages transfer-related operations with a suite of endpoints tailored to cover various functionalities:

  1. Create Internal Fiat Transfer: This endpoint allows customers to conduct internal fund transfers between two customer asset accounts within the system. The users need to specify the source and destination account IDs, the amount to be transferred, and a reference note for the transaction.

  2. Create External Fiat Transfer: Customers can perform external transfers from their asset account using this endpoint. It supports both domestic and international transfers, requiring information about the source account, transfer type, payee details, saved payee preferences, amount, reference note, and the purpose code for the transaction.

  3. Create External Fiat Transfer With Originator: Customers can perform external transfers from their asset account using this endpoint. User's have the ability to set the transaction's originator, and thus affect how the sender's details appear in the receiver's account. It supports both domestic and international transfers, requiring information about the source account, transfer type, payee details, saved payee preferences, amount, reference note, and the purpose code for the transaction.

  4. Get Purpose Codes: This endpoint provides a list of available purpose codes that are to be used for external fiat transfers. It helps in categorizing the transfer types for internal use, such as "Transfer to own account" or "Family Maintenance".

  5. Create Internal Crypto Transfer: This endpoint allows customers to conduct internal cryptocurrency transfers between two customer asset accounts within the system. The users need to specify the source and destination account IDs, the amount to be transferred.

  6. Get Reverse Inbound Transfer Details - This operation gives a user necessary details to call the POST endpoint. This includes a list of reasons for transaction reversal.

  7. Reverse Inbound Transfer - This operation allows the user to reverse an inbound external transfer.


Create Internal Fiat Transfer

Make an internal fiat transfer between two customer asset accounts.

Example Request Body

{
   "SourceAccountId":2141,
   "DestinationAccountId":2143,
   "Amount": 1000,
   "Reference": "Internal Fiat Transfer Test"
}

Example Success Response

{
    "id": 1008,
    "status": "1",
    "errors": []
}

Create External Fiat Transfer

Make an external transfer from a customer asset account, using either a Wire or ACH. Refer to Purpose Codes to categorize a transfer.

  • Endpoint: /api/v3/customer/transfers/fiat/createexternaltransfer

  • Method: POST

Transfer Types

Create External Fiat Transfer currently supports four different TransferTypes. Depending on your account type, you can access the following:

  1. Wire - FedWire, available to US accounts.

  2. ACH - Available to US accounts.

  3. RTP - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.

  4. SWIFT - For international accounts.

Request Body Parameters

Parameter NameTypeDescription

transmitter

Object, Required for Financial Institutions

Information relating to the transmittere of payment

transmitter.firstPartyTransfer

Boolean

True if the payment is a first party transfer. If true, other transmitter fields are not required.

transmitter.type

String

'Company' or 'Individual'

transmitter.dateOfBirth

datetime

If Transmitter type is 'Individual', date of birth is required

transmitter.name

String

Name of Transmitter

transmitter.accountNumber

String, Optional

Account Number for the Transmitter

transmitter.addressLine1

String

Address Line 1 for transmitter

transmitter.addressLine2

String, Optional

Address Line 2 for transmitter

transmitter.townCity

String

Town / City for transmitter

transmitter.state

String

State / Province for transmitter

transmitter.postcode

String

Post Code for transmitter

transmitter.countryCode

String

3 Letter Country Code for transmitter (ex. USA)

payee

Object, Required

Payee / Beneficary information

payee.payeesId

Number

Optional Payees ID of an existing payee, for sending payments to an existing payee. If provided, the other payee fields are not required.

payee.name

String

Name of Payee

payee.type

String

'Personal' or 'Company'

payee.countryCode

String

3 Letter Country Code for recieving bank (ex. USA)

payee.bankName

String

Name of Receiving Bank

payee.routingNumber

String

ABA Routing Number, not required if swiftCode is provided

payee.swiftCode

String

SWIFT Bic, not required if routingNumber is provided

payee.intermediarySwiftCode

String, Optional

Optional Intermediary Bank SWIFT Bic. Only available for SWIFT transfers.

payee.accountNumber

String

Account Number of payee

payee.accountName

String

Name of the payee's account. If unknown, use the payee name

payee.addressLine1

String

Address Line 1 for payee

payee.addressLine2

String, Optional

Address Line 2 for payee

payee.townCity

String

Town / City for payee

payee.state

String

State / Province for payee

payee.postcode

String

Post Code for payee

payee.addressCountryCode

String

3 Letter Country Code for payee (ex. USA)

bSavePayee

Boolean

True if you would like to save the payee details for future use

sourceAccountId

Number

Account ID corresponding to the account to be debited

transferType

String

Transfer rail (ex. 'SWIFT', 'Wire', etc)

amount

Number

Amount to be sent. The currency is implied by the currency of the sourceAccountId

bankFeeSplitType

String

For SWIFT transfers only, specify 'Full Bank Fee', 'Half Bank Fee', or 'No Bank Fee'. If none is provided, default is 'Half Bank Fee'

reference

String

Reference message to be sent to the receiving bank. (Limit 140 characters)

purposeCode

String, Enum

Refer to our list of Purpose Codes. Required for Wire transfers sent to an international payee.

purpose

String

If a purposeCode is not provided, you may use purpose, which is a string to specify the purpose of the payment (max 100 chars). You must provide either purpose or purposeCode, however purposeCode is required for Wire transfers sent to payees outside the USA

Transfer Purpose

All external transfers require a payment purpose to be submitted in the request body. You can either select a payment purpose (PurposeCode) from our list of payment purposes or alternatively submit a string for the Purpose field.

Note: You must submit either PurposeCode or Purpose, but not both. PuposeCode is required for sending international transfers from a USA based account.

Param NameTypeDescription

PurposeCode

String

Purpose

String

Provide a string for purpose reason. Limit 100 chars. [a-z], [A-Z], [0-9]

Payee Request Parameters

When configuring a payee, you can either use payeesId to use an existing payee, or provide payee information directly. Additionally, you can refer to the Payees API Endpoints to access various functionality such as creating, retrieving, modifying, and deleting payees.

{
  ...
  "payee": {
    // Option 1: Use payeesId to reference a Payee
    "payeesId": 0,
    
    // Option 2: Use the following fields to detail a payee
    
    //Either Routing Number or Swift Code is available
    "routingNumber": "string",
    "swiftCode": "string",
    "bankName": "string",
    "countryCode": "string",
    "intermediarySwiftCode":"string",
    "accountNumber": "string",
    "accountName": "string",
    
    "type": "string",
    "name": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressCountryCode": "string",
    "townCity": "string",
    "state": "string",
    "postcode": "string"
  },
  ...
}

Transmitter Information

Financial Institutions are required to submit information regarding the transmitter of a payment. You can submit this information in the transmitter object. For transactions that are first party transfer, you can specify firstPartyTransfer: true

Third Party Payment Example

{
    ...
    "transmitter": {
        "firstPartyTransfer": false,
        
        "name": "John Doe",
        "type": "Company",
        "dateOfBirth": "1990-10-08T00:00:00.000Z"
        "accountNumber": "1234567890",
        "addressLine1": "123 Main St",
        "addressLine2": "Unit 1A",
        "townCity": "Cityville",
        "state": "WY",
        "postcode": "12345",
        "countryCode": "USA"
        
  },
  ...
}

First Party Payment Example

{
    ...
    "transmitter": {
        "firstPartyTransfer": true
  },
  ...
}

Example Request Body

The format of the request body is different between Domestic USA transfers and international transfers. Refer to the following examples for reference:

Domestic Wire Transfer Request Body

{
        "sourceAccountId":2141,
        "transferType": "Wire",
        "payee":{
                "countryCode":"USA",
                "bankName": "ABC Bank",
                "routingNumber":"125000105",
                "accountNumber":"2140632999",
                "accountName":"Test account",
                "type":"Personal",
                "name":"Test Account",
                "addressLine1":"123 Main St",
                "townCity":"New York",
                "state":"NY",
                "postcode":"10001"
        },
        "bSavePayee":true, 
        "amount": 100,
        "reference": "Test Transfer", 
        "purposeCode" : "PUC002"
}

International Swift Transfer Request Body

International transfers utilize the SWIFT TransferType. Customers can specify the BankFeeSplitType, which enables a customer to decide the bearer of bank charges. You can choose between the following values for BankFeeSplitType:

  • "Full Bank Fee" - This option is known as 'OURS'

  • "Half Bank Fee" - This option is known as 'SHA'

  • "No Bank Fee" - This option is known as 'BEN'

{
        "sourceAccountId": 2141,
        "transferType": "SWIFT",
        "bankFeeSplitType": "Full Bank Fee",
        "transmitter": {
                "firstPartyTransfer": false,
                "name": "John Doe",
                "accountNumber": "1234567890",
                "addressLine1": "123 Main St",
                "addressLine2": "Unit 1A",
                "townCity": "Cityville",
                "state": "WY",
                "postcode": "12345",
                "countryCode": "USA",
                "type": "Individual",
                "dateOfBirth": "1990-10-08T00:00:00.000Z"
        },
        "payee": {
                "countryCode": "SGP",
                "bankName": "ABC Bank",
                "swiftCode": "DBSSSGSG",
                "intermediaryBic":"XXXX",
                "accountNumber": "12342346545123",
                "accountName": "Checking Account",
                "type":"Company",
                "name": "Sample Company LLC",
                "addressLine1": "62 UBI road 1",
                "townCity": "Oxley Bizhub 2",
                "postcode": "408734"
        },
        "bSavePayee": true,
        "amount": 50,
        "reference": "Transaction reference to be sent to beneficiary (140 chars)", 
        "purpose": "Purpose of the transfer (100 chars)"
}

Example Success Response

{
    "id": 22026,
    "details": {
        "id": 30939,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": -10,
        "description": "External transfer - Family Maintenance",
        "dateTime": "2024-02-15T17:05:09.97+00:00",
        "bPending": true
    },
    "status": "1",
    "errors": []
}

Create External Fiat Transfer With Originator

Make an external transfer with a user defined originator from a customer asset account, using either a Wire or ACH. Refer to Purpose Codes to categorize a transfer.

Transfer Types

Create External Fiat Transfer currently supports four different TransferTypes. Depending on your account type, you can access the following:

  1. Wire - FedWire, available to US accounts.

  2. ACH - Available to US accounts.

  3. RTP - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.

  4. SWIFT - For international accounts.

Request Body Parameters

Parameter NameTypeDescription

transmitter

Object, Required for Financial Institutions

Information relating to the transmittere of payment

transmitter.firstPartyTransfer

Boolean

True if the payment is a first party transfer. If true, other transmitter fields are not required.

transmitter.name

String

Name of Transmitter

transmitter.accountNumber

String, Optional

Account Number for the Transmitter

transmitter.addressLine1

String

Address Line 1 for transmitter

transmitter.addressLine2

String, Optional

Address Line 2 for transmitter

transmitter.townCity

String

Town / City for transmitter

transmitter.state

String

State / Province for transmitter

transmitter.postcode

String

Post Code for transmitter

transmitter.countryCode

String

3 Letter Country Code for transmitter (ex. USA)

payee

Object, Required

Payee / Beneficary information

payee.payeesId

Number

Optional Payees ID of an existing payee, for sending payments to an existing payee. If provided, the other payee fields are not required.

payee.name

String

Name of Payee

payee.type

String

'Personal' or 'Company'

payee.countryCode

String

3 Letter Country Code for recieving bank (ex. USA)

payee.bankName

String

Name of Receiving Bank

payee.routingNumber

String

ABA Routing Number, not required if swiftCode is provided

payee.swiftCode

String

SWIFT Bic, not required if routingNumber is provided

payee.intermediarySwiftCode

String, Optional

Optional Intermediary Bank SWIFT Bic. Only available for SWIFT transfers.

payee.accountNumber

String

Account Number of payee

payee.accountName

String

Name of the payee's account. If unknown, use the payee name

payee.addressLine1

String

Address Line 1 for payee

payee.addressLine2

String, Optional

Address Line 2 for payee

payee.townCity

String

Town / City for payee

payee.state

String

State / Province for payee

payee.postcode

String

Post Code for payee

payee.addressCountryCode

String

3 Letter Country Code for payee (ex. USA)

bSavePayee

Boolean

True if you would like to save the payee details for future use

originator

Object

Information relating to the originator

originator.companyId

String

Company ID of the originator

originator.name

String

Name of Orignator

originator.AddressLine1

String

Address line 1 for originator

originator.AddressLine2

String

Address line 2 for originator

originator.AddressLine3

String

Address line 3 for originator

originator.Data

String

Additional data to be sent with Originator Information

sourceAccountId

Number

Account ID corresponding to the account to be debited

transferType

String

Transfer rail (ex. 'SWIFT', 'Wire', etc)

amount

Number

Amount to be sent. The currency is implied by the currency of the sourceAccountId

bankFeeSplitType

String

For SWIFT transfers only, specify 'Full Bank Fee', 'Half Bank Fee', or 'No Bank Fee'. If none is provided, default is 'Half Bank Fee'

reference

String

Reference message to be sent to the receiving bank. (Limit 140 characters)

purposeCode

String, Enum

Refer to our list of Purpose Codes. Required for Wire transfers sent to an international payee.

purpose

String

If a purposeCode is not provided, you may use purpose, which is a string to specify the purpose of the payment (max 100 chars). You must provide either purpose or purposeCode, however purposeCode is required for Wire transfers sent to payees outside the USA

Payee Request Parameters

When configuring a payee, you can either use payeesId to use an existing payee, or provide payee information directly. Additionally, you can refer to the Payees API Endpoints to access various functionality such as creating, retrieving, modifying, and deleting payees.

{
  ...
  "payee": {
    // Option 1: Use payeesId to reference a Payee
    "payeesId": 0,
    
    // Option 2: Use the following fields to detail a payee
    
    //Either Routing Number or Swift Code is available
    "routingNumber": "string",
    "swiftCode": "string",
    "bankName": "string",
    "countryCode": "string",
    "intermediarySwiftCode":"string",
    "accountNumber": "string",
    "accountName": "string",
    
    "type": "string",
    "name": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressCountryCode": "string",
    "townCity": "string",
    "state": "string",
    "postcode": "string"
  },
  ...
}

Transmitter Information

Financial Institutions are required to submit information regarding the transmitter of a payment. You can submit this information in the transmitter object.

Third Party Payment Example

{
    ...
    "transmitter": {
        "firstPartyTransfer": false,
        
        "name": "John Doe",
        "accountNumber": "1234567890",
        "addressLine1": "123 Main St",
        "addressLine2": "Unit 1A",
        "townCity": "Cityville",
        "state": "WY",
        "postcode": "12345",
        "countryCode": "USA"
  },
  ...
}

First Party Payment Example

{
    ...
    "transmitter": {
        "firstPartyTransfer": true
  },
  ...
}

Originator Request Parameters

The settable parameters for the originator depend on whether the transfer is a Wire or an ACH transfer.

{
  ...
  "Originator":{
        //Required for ACH transfers
        "CompanyId":"string",
        
        //Required
        "Name":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine1":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine2":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine3":"string",
        
        //Optional for ACH transfers. Must be null for Wire transfers
        "Data":"string"
    },
  ...
}

Example Request Body

The format of the request body is different between Domestic USA transfers and international transfers. Refer to the following examples for reference:

Domestic Wire Transfer Request Body

{
   "SourceAccountId":2141,
   "TransferType":"Wire",
    "Payee":{
        "CountryCode":"USA",
        "RoutingNumber":"125000105",
        "AccountNumber":"2140632999",
        "AccountName":"Test account",
        "Type":"Personal",
        "Name":"Test Account",
        "AddressLine1":"1 TestAddress",
        "TownCity":"TestTown",
        "State":"TestCounty",
        "Postcode":"N19AA"
    },
    "Originator":{
        "CompanyId":null,
        "Name":"Test name",
        "AddressLine1":"street address",
        "AddressLine2":"town",
        "AddressLine3":"country",
        "Data":null
    },
    "bSavePayee":true,
   "Amount": 10,
   "Reference": "Test Transfer",
   "PurposeCode" : "PUC002"
}

International Wire Transfer Request Body

{
    "SourceAccountId": 2141,
    "TransferType": "Wire",
    "Payee": {
        "CountryCode": "SGP",
        "SwiftCode": "DBSSSGSG",
        "IntermediaryBic":"XXXX",
        "AccountNumber": "12342346545123",
        "AccountName": "Sebi Scaria",
        "Type":"Company",
        "Name": "Sebi Scaria",
        "AddressLine1": "62 UBI road 1",
        "TownCity": "Oxley Bizhub 2",
        "Postcode": "408734"
    },
    "Originator":{
        "CompanyId":null,
        "Name":"Test name",
        "AddressLine1":"street address",
        "AddressLine2":"town",
        "AddressLine3":"country",
        "Data":null
    },
    "bSavePayee":true,
    "Amount": 50,
    "Reference": "Test Transfer",
    "PurposeCode": "PUC002"
}

Example Success Response

{
    "id": 22026,
    "details": {
        "id": 30939,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": -10,
        "description": "External transfer - Family Maintenance",
        "dateTime": "2024-02-15T17:05:09.97+00:00",
        "bPending": true
    },
    "status": "1",
    "errors": []
}

Get Purpose Codes

Get list of available purpose codes to be used for external fiat transfer.

Example Success Response

{
    "id": 0,
    "details": [
        {
            "code": "PUC001",
            "description": "Transfer to own account"
        },
        {
            "code": "PUC002",
            "description": "Family Maintenance"
        }
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "status": "1",
    "errors": []
}

Create Internal Crypto Transfer

This endpoint initiates a transfer of crypto currency between two asset accounts that are accessible by a manager. The endpoint requires parameters for the source account ID, the destination account ID, and the amount for the transfer. The asset to be transferred is inferred by the asset account ID.

  • Endpoint: /api/v1/customer/accounts/crypto/move

  • Method: POST

Request Body Example

{
    "fromAccountsId": 1001, // Integer - Required
    "toAccountsId" : 1002, // Integer - Required
    "amount": 0.01 // Decimal - Required
}

Response Body Example

{
    "id": 0,
    "details": {
        "customersId": 1001,
        "customerReference": "your-customer-reference",
        "fromTransaction": {
            "id": 10001,
            "accountsId": 1001,
            "fromTransactionsId": null,
            "fromAccountsId": null,
            "toTransactionsId": 10002,
            "toAccountsId": 1002,
            "amount": -0.010000000000000000,
            "description": "Transfer of crypto to managing account 1001",
            "dateTime": "2024-01-01T18:21:39.7633333+00:00",
            "bPending": true
        },
        "toTransaction": {
            "id": 10002,
            "accountsId": 1002,
            "fromTransactionsId": 10001,
            "fromAccountsId": 1001,
            "toTransactionsId": null,
            "toAccountsId": null,
            "amount": 0.010000000000000000,
            "description": "Receipt of crypto from managee account 1002",
            "dateTime": "2024-01-01T18:21:39.77+00:00",
            "bPending": true
        }
    },
    "status": "1",
    "errors": []
}

Get Reverse Inbound Transfer Details

This operation gives the user necessary details to call the POST endpoint to reverse an inbound transfer.

  • Endpoint: /api/v1/customer/accounts/reverse-inbound-transfer

  • Method: GET

  • Query Parameters:

    • customersId (Integer): The ID of the customer account from which the withdrawal is to be made.

Response Body Parameters:

  • id (Integer): A reference ID for the transaction; not used in the example.

  • details.purposes (JSON Array): List of possible purposes for reversal.

  • details.purposes.id (Integer): The ID of the purpose.

  • details.purposes.name (String): Description of the purpose.

Success Response Example:

{
    "id": 0,
    "details": {
        "purposes": [
            {
                "id": 1000,
                "name": "Unable to Identify Beneficiary"
            },
            {
                "id": 1001,
                "name": "Unexpected Transaction"
            },
            {
                "id": 1002,
                "name": "Transaction Not Allowed"
            },
            {
                "id": 1003,
                "name": "Other"
            }
        ]
    },
    "status": "1",
    "errors": []
}

Reverse Inbound Transfer

This operation allows the user to reverse an inbound transfer.

  • Endpoint: /api/v1/customer/accounts/reverse-inbound-transfer

  • Method: POST

  • Request Body Parameters:

    • customersId (Integer): The ID of the customer account from which the withdrawal is to be made.

Request Example:

{
    "customersId":2036,
    "transactionId":18410,
    "purposeId":1001,
    "purposeOther":null
}

Response Body Parameters:

  • id (Integer): A reference ID for the transaction; not used in the example.

  • details.transactionId (JSON Array): Id of the transaction being reversed.

Success Response Example:

{
    "id": 0,
    "details": {
        "transactionId": 18410
    },
    "status": "1",
    "errors": []
}

Last updated