Bank Transfer

On this page, the details of Bank Transfer are shown with examples and API endpoints to work with.

Summary

Bank Transfer works in a way so that the users can send money to accounts from different banks. Users have to add recipients first to send money, the recipients can be added with information such as iban, bic, name and currency. After the user has added a recipient, the user can get the list of recipients and select the recipient to send the money.

Bank Transfer Flow

1. Select Recipient

2. Select Your Bank Account

3. Enter Transaction Details

4. Approve Transaction

How to add a recipient

To add a recipient, you will need the following information about the account holder:

1. bic

2. currency

3. iban

4. name

After you have the listed details, you can add a recipient with the following API endpoint under the recipient controller:

addRecipient

Required scopes - transfers

POST//transfers:8080/v1/recipients

Body

application/json

body

bic*string

currency*CurrencyUnit

iban*string

name*string

Response

201401403404

Created

Body

application/json

idstring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/recipients', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "bic": "text",
      "currency": {},
      "iban": "text"
    }),
});
const data = await response.json();

Response

{
  "id": "text"
}

You will have to pass the bearer token as the auth token with the request for it to work

How to get all added recipients

To get the list of the recipients added to the account, you will have to make a GET request to the below API endpoint:

getRecipients

Required scopes - transfers

GET//transfers:8080/v1/recipients

Response

200401403404

OK

Body

application/json

addressAddress

bicstring

currencyCurrencyUnit

ibanstring

idstring

namestring

ukAccountNumberstring

ukSortCodestring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/recipients', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "address": {
      "addressLine1": "text",
      "addressLine2": "text",
      "addressLine3": "text",
      "city": "text",
      "country": "text",
      "name": "text",
      "postalCode": "text"
    },
    "bic": "text",
    "currency": {
      "context": {
        "empty": false,
        "providerName": "text"
      },
      "currencyCode": "text"
    },
    "iban": "text",
    "id": "text",
    "name": "text",
    "ukAccountNumber": "text",
    "ukSortCode": "text"
  }
]

The response will contain a list of objects containing the receiver's details such as name, iban, currency, bic and the unique id for that specific recipient. A sample response is given below:

[
    {
        "id": "66a60282-9821-4751-9a9e-e1d6f83ea6b7",
        "name": "John Doe",
        "iban": "Sample iban Number",
        "bic": "TESTBIC",
        "currency": "EUR"
    },
    {
        "id": "1f41f279-7c88-4172-9fcf-7ae1599216b1",
        "name": "John Doe 2",
        "iban": "Sample iban Number",
        "bic": "TESTBIC",
        "currency": "EUR"
    }
]

The above response shows that the account has two recipients added to the account.

How to get a specific recipient detail

To get specific recipient details, you must pass the recipient id in the URL. Use the below API endpoint to get the details of that recipient:

getRecipient

Required scopes - transfers

GET//transfers:8080/v1/recipients/{id}

Path parameters

id*string

id

Response

200401403404

OK

Body

application/json

addressAddress

bicstring

currencyCurrencyUnit

ibanstring

idstring

namestring

ukAccountNumberstring

ukSortCodestring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/recipients/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "address": {
    "addressLine1": "text",
    "addressLine2": "text",
    "addressLine3": "text",
    "city": "text",
    "country": "text",
    "name": "text",
    "postalCode": "text"
  },
  "bic": "text",
  "currency": {
    "context": {
      "empty": false,
      "providerName": "text"
    },
    "currencyCode": "text"
  },
  "iban": "text",
  "id": "text",
  "name": "text",
  "ukAccountNumber": "text",
  "ukSortCode": "text"
}

The response will contain an object containing the details of the recipient. A sample response is given below:

{
    "id": "1f41f279-7c88-4172-9fcf-7ae1599216b1",
    "name": "John Doe",
    "iban": "Sample IBAN",
    "bic": "TEST123",
    "currency": "EUR"
}

How to delete a recipient

To delete a recipient, make a DELETE request with the id of the recipient in the path of the request URL.

deleteRecipient

Required scopes - transfers

DELETE//transfers:8080/v1/recipients/{id}

Path parameters

id*integer (int32)

id

Response

200204401403

OK

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/recipients/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

After selecting the recipient, you will have to initiate the transfer by selecting the account to that you are trying to send the money. Along with this, you can also send a message that will be delivered alongside this transaction to the recipient's account.

To get the list of your account, make a GET request to the below endpoint:

getAccounts

Required scopes - accounts

GET//accounts:8080/v1/accounts

Response

200401403404

OK

Body

application/json

accountProviderenum

RAILSBANKFIGOCONTISWISEADDITIVSINCURASWAN

balanceMonetaryAmountModel

bankNamestring

bicstring

ibanstring

idstring

imageUristring

logostring

namestring

sharedConfigurationSharedConfiguration

sharingConfigurationsarray of SharingConfigurationResponseBody

ukAccountNumberstring

ukSortCodestring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/accounts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "accountProvider": "RAILSBANK",
    "balance": {
      "amount": 0,
      "currency": "text"
    },
    "bankName": "text",
    "bic": "text",
    "iban": "text",
    "id": "text",
    "imageUri": "text",
    "logo": "text",
    "name": "text",
    "sharedConfiguration": {
      "ownerName": "text",
      "permissions": [
        "TRANSFERS"
      ],
      "sharedWithNames": [
        "text"
      ]
    },
    "sharingConfigurations": [
      {
        "accountId": "text",
        "permissions": [
          "TRANSFERS"
        ],
        "sharedWithContact": {
          "detail": "text",
          "type": "EMAIL"
        },
        "sharedWithName": "text",
        "sharingId": "text",
        "status": "PENDING"
      }
    ],
    "ukAccountNumber": "text",
    "ukSortCode": "text"
  }
]

This request will send a list of the account associated with the credential.

To make the transfer, you have to use the below API endpoint:

initiateTransfer

Required scopes - transfers

POST//transfers:8080/v1/transfers

Body

application/json

body

amount*MonetaryAmountModel

attachmentsarray of Attachment

fromAccount*InstructedAccount

message*string

scheduleTransferSchedule

toAccount*InstructedAccount

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": {},
      "fromAccount": {},
      "toAccount": {},
      "message": "text"
    }),
});
const data = await response.json();

To make the transfer request, you need the account number (id from the previous response) and the format. For the toAccount, this is also similar, but the data will be used from the selected recipient's information. Get the amount value and the execution date from the user to make the transfer API call. You can also add a message to the transaction.

After making the transfer request, the response will contain an id, as this transaction needs to be approved. For approving the transaction, you will have to call the /v1/transfers/{{transferID}}/approvals API with the id that you received from the last response. For approval, you will need the PIN number.

For this request, you have to make sure that a challenge id is available as 'X-AAZZUR-DEVICE-CHALLENGE' and a signature is available as 'X-AAZZUR-SIGNATURE'. To know more about how to generate it, please read through the process available on the Device Verification Page.

approveTransfer

Required scopes - transfers Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//transfers:8080/v1/transfers/{id}/approvals

Path parameters

id*string

id

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers/{id}/approvals', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Users can cancel their transfer until it is not approved by the recipient of the transfer request. To cancel a transfer request, you have to use the id in the parameter.

cancelTransfer

Required scopes - transfers Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//transfers:8080/v1/transfers/{id}/cancellation

Path parameters

id*string

id

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers/{id}/cancellation', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

On the transfer initiation, you can set the transfer as a recurring payment but if you want to change the scheduled time of the transfer, then make a PATCH request to the /v1/transfer/{id} endpoint. Here, the id is the id of the transfer request.

For this request, you have to make sure that a challenge id is available as 'X-AAZZUR-DEVICE-CHALLENGE' and a signature is available as 'X-AAZZUR-SIGNATURE'. To know more about how to generate it, please read through the process available on the Device Verification Page.

changeSchedule

Required scopes - transfers Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

PATCH//transfers:8080/v1/transfers/{id}

Path parameters

id*string

id

Body

application/json

body

scheduleTransferSchedule

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

Users can also cancel a transfer request. The difference between cancelling a transfer request and rejecting a request is that cancellation is made by the same user who has created the request. On the other hand, rejection is done by the user to whom the transfer request is being sent.

The cancellation transfer request requires an id of the transfer request. The successful response will return the status of the cancellation request.

cancel

Required scopes - transfers

DELETE//transfers:8080/v1/transfer-requests/{id}

Path parameters

id*string

id

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfer-requests/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

To reject a request, the request needs the id of the transfer request. The id can be found in the transfer request list available in an account by making a GET request to the v1/transfer-requests. The response is going to contain the status of the request.

rejectTransfer

Required scopes - transfers

POST//transfers:8080/v1/transfers/{id}/rejection

Path parameters

id*string

id

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers/{id}/rejection', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

When sending money, users can request money from other users or to simply put make a transfer request. The transfer-request-controller works with the transfer requests.

A user account can have multiple transfer requests. To get all the account transfer requests, make a GET request. The response will contain a list of the transfer requests containing the amount, id, name, message, etc.

Note: You will have to pass the oauth token as the bearer token for the request and make sure that the transfer scope is in the scope list.

getTransferRequests

Required scopes - transfers

GET//transfers:8080/v1/transfer-requests

Query parameters

Response

200401403404

OK

Body

application/json

amountMonetaryAmountModel

idstring

imageUristring

messagestring

namestring

requestDatestring (date-time)

requestTypeenum

REQUESTSPLIT_BILL

requestedContactContactDetail

statusenum

REQUESTEDREJECTEDEXPIREDACCEPTED

toAccountInstructedAccount

typeenum

OUTGOINGINCOMING

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfer-requests', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "amount": {
      "amount": 0,
      "currency": "text"
    },
    "id": "text",
    "imageUri": "text",
    "message": "text",
    "name": "text",
    "requestDate": "2024-05-06T18:06:06.386Z",
    "requestType": "REQUEST",
    "requestedContact": {
      "detail": "text",
      "type": "EMAIL"
    },
    "status": "REQUESTED",
    "toAccount": {
      "format": "INTERNAL",
      "name": "text",
      "number": "text"
    },
    "type": "OUTGOING"
  }
]

transfers-controller

The transfer controller deals with the transfers of an account, including the initialization of a transfer, getting transfer details, etc.

To get the list of the transfers, make a GET request to /v1/transfer. The successful response will contain a list of the transfer request containing the amount, message and other information about the transfer. Please check out the 200:OK Response schema to get the full details.

getTransfers

Required scopes - transfers

GET//transfers:8080/v1/transfers

Query parameters

Response

200401403404

OK

Body

application/json

amountMonetaryAmountModel

attachmentsarray of Attachment

createdAtstring (date-time)

fromAccountInstructedAccount

idstring

initiatedByAnotherCustomerboolean

initiatedByAnotherUserboolean

initiatedByNamestring

messagestring

nextScheduledDatestring (date)

scheduleTransferSchedule

stateenum

CREATEDPROCESSINGPROCESSEDFAILEDCANCELLEDPENDING_OWNER_APPROVALAPPROVEDREJECTED_BY_OWNER

toAccountInstructedAccount

Request

JavaScriptCurl

const response = await fetch('//transfers:8080/v1/transfers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "amount": {
      "amount": 0,
      "currency": "text"
    },
    "attachments": [
      {
        "link": "text",
        "type": "IMAGE"
      }
    ],
    "createdAt": "2024-05-06T18:06:06.386Z",
    "fromAccount": {
      "format": "INTERNAL",
      "name": "text",
      "number": "text"
    },
    "id": "text",
    "initiatedByAnotherCustomer": false,
    "initiatedByAnotherUser": false,
    "initiatedByName": "text",
    "message": "text",
    "nextScheduledDate": "2024-05-06",
    "schedule": {
      "endDate": "2024-05-06",
      "startDate": "2024-05-06",
      "transferFrequency": "WEEKLY"
    },
    "state": "CREATED",
    "toAccount": {
      "format": "INTERNAL",
      "name": "text",
      "number": "text"
    }
  }
]