Transfer Money

On this page, you will be guided how to send or transfer money to another user's account. The section also contains step by step guide with the API endpoints to make the transfer successfully.

Summary

One of the most important features of a banking application is to send or transfer money to another account. The term can be simple but there are multiple steps to do this process and things can become complicated if the idea is not clear and fully understood.

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.

Steps to send money

1. Discover contacts

2. Add Recipients or Manage Recipients

3. Initiating the transfer

4. Managing the transfer -> Approve / Reject

1. Discover Contacts

The first step of making a transaction is to discover the available accounts in your contact list. The account that you are trying to send the money has unique ids attached to it and in this case, the mobile number and the email address are associated with the account. If a person is on your contact list then you can see them and add them as a recipient to your account. A recipient can also be the second account that you have saved in your device contact list.

To find the available contacts, the first step is to get the contact read permission on the device itself. Without this permission, you cannot discover the accounts that are available in your contact list. To discover available contacts make a POST request using the /v1/contacts-discovery endpoint.

The phone numbers and email addresses have to be sent after hashing using the sha256 method. A sample request body is given below:

[
    {
        "id": "dev123",
        "emailHash" : "da4ea0932830481fb85ca8208da7983d7e51d780ec48db49d44ec89b82da2bcc",
        "phoneNumberHash": "653eb668de2d0073a67f01770f6a272861c9976551a018f9058b198b90048787" 
    }
]

discoverContacts

Required scopes - transfers

POST//transfers:8080/v1/contacts-discovery

Body

application/json

body

emailHashstring

idstring

phoneNumberHashstring

Response

200201401403404

OK

Body

application/json

emailHashstring

idstring

phoneNumberHashstring

Request

JavaScriptCurl

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

Response

[
  {
    "emailHash": "text",
    "id": "text",
    "phoneNumberHash": "text"
  }
]

2. Add Recipients or Manage Contacts

The recipients Controller works with the functions of the recipients of an account. To get the list of the recipients in an account, make a GET request to get the list of the recipients available on the account. The response will return an array containing the details of the recipients.

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"
  }
]

When you have to add a recipient to an account, you will have to make a POST request with the recipient's details. To add a recipient the below information of a recipient is required:

• bic number

• currency

• iban number

• name

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

The response will contain an id object that is referencing the recipient id. A sample response is given below:

{
    "id": "b948986b-db9d-412f-a94f-5a2b6bc035e2"
}

3. Initiate Transfer

Initiating the transfer of money can be of two ways. A) An account is requesting money to another account or B) An account transferring money to another account.

A) Money Request

When sending money, users can request money to other users or 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 transfer requests of the account, make a GET request. The response is going to contain a list of the transfer requests containing the amount, id, name, message, etc.

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-06T11:45:46.353Z",
    "requestType": "REQUEST",
    "requestedContact": {
      "detail": "text",
      "type": "EMAIL"
    },
    "status": "REQUESTED",
    "toAccount": {
      "format": "INTERNAL",
      "name": "text",
      "number": "text"
    },
    "type": "OUTGOING"
  }
]

To make a transfer request, you will have to prepare the data needed for the creation of the transfer and make a POST request to the below API endpoint. A successful response is going to return the transfer id as a JSON response.

createRequest

Required scopes - transfers

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

Body

application/json

body

amount*MonetaryAmountModel

attachmentsarray of Attachment

contactDetail*ContactDetail

message*string

requestType*enum

REQUESTSPLIT_BILL

toAccount*InstructedAccount

Response

201202401403404

Created

Request

JavaScriptCurl

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

Users can also cancel a transfer request, the difference between cancelling a transfer request and rejecting a request is that cancellation is done 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 list of the transfer request 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();

B) An account transferring money to another account

To start the transfer process, make a POST request with the data required for the initialization. There are some options available for the users to choose from. For example, if the user wants to attach some images then the attachment object should be used. Users can add multiple attachments in a transfer.

Users can set up the transfer as a recurring payment as well by providing the 'schedule' property in the body. There can be an end date for the recurring payment but it's not a mandatory one. Users can cancel or change the scheduled date later on.

The mandatory fields are marked with a * sign.

initiateTransfer

Required scopes - transfers

POST//transfers:8080/v1/transfers

Body

application/json

body

amount*MonetaryAmountModel

attachmentsarray of Attachment

fromAccount*InstructedAccount

messagestring

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": {
        "format": "INTERNAL",
        "number": "text"
      },
      "toAccount": {
        "format": "INTERNAL",
        "number": "text"
      }
    }),
});
const data = await response.json();

On the initiation of the transfer, 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 /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.

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();