Beneficiaries

Overview

To begin making payments to other accounts, beneficiaries must be created. The following guide provides a list of steps to make a payment to an individual or a business successfully.

Step 1. Lookup a Country's Bank Requirements

GET - Country Bank Requirements

In the example below, the request is made by assigning the ccyCountry and ccyCurrency values as CA and CAD respectively.

Depending on the country, there may be specific requirements such as, the bank's address having to be entered on the payment request - as is the case with Canadian bank transfers. As shown below, RequiresBenAddress on line 11 is set to true, thereby establishing the need to fill out the Beneficiary's bank address details.

RESPONSE

{
    "Content": {
        "Model": {
            "BankRequirements": {
                "CountryCode": "CA",
                "LocalCurrency": "CAD",
                "UsesIban": false,
                "UsesBankCode": true,
                "BankCodeDescription": "SWIFT / Bank Code",
                "UsesSepa": false,
                "RequiresBenAddress": true,
                "UsesSortCode": false,
                "UsesSwift": true,
                "UsesAccountNumber": true,
                "ApiStatusCode": 100,
                "ApiStatus": "IsValid",
                "ApiStatusDescription": "Valid Operation"
            }

Step 2. Lookup Bank Details

To retrieve a beneficiary's bank details:

  1. Call POST - Retrieve Bank Information Details. This information can then be used when adding the beneficiary. To initiate a request, the Account object is required - as shown on the table below:

Account Object

NameDescriptionTypeRequired/Optional
CountryThe beneficiary's country. Consists of a two-letter country code as per ISO 3166-1 alpha-2.strRequired
CurrencyThe beneficiary's currency. Consists of a three-letter currency code as per ISO 4217.strRequired
IBANThe beneficiary's IBAN. Consists of up to 34 alphanumeric characters. As per ISO 13616:2020.strOptional
SWIFTThe beneficiary's SWIFT code, as per ISO 9362:2022. Consists of 8 or 11 characters.strOptional
SortCodeThe beneficiary's Sort Code. This is a six-digit number applicable to UK accounts only.strRequired for UK accounts.
AccountNumberThe beneficiary's account number. This is an eight-digit number applicable to UK accounts only.strRequired for UK accounts.

REQUEST

In the example request body below, Caxton's UK account number and sort code are entered:

curl --location 'https://caxapi-integration.azurewebsites.net/api/beneficiaries/retrieve-bank-details' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--data '{
 "COUNTRY":"GB" ,
 "CURRENCY":"GBP", 
 //"IBAN": <IBAN>,
 //"SWIFT": <SWIFT>,
 "SORTCODE": "160032",
 "ACCOUNTNUMBER": "10106021"
}'

Consequently, the response displays the corresponding account details, such as the name of the bank, branch location, SWIFT code, etc.

RESPONSE

{
    "Content": {
        "Model": {
            "BankDetails": [
                {
                    "AccountName": "Caxton Payments Limited",
                    "Currency": "GBP",
                    "BankName": "The Royal Bank of Scotland plc",
                    "AccountNumber": "<accountnumber>",
                    "IbanNumber": null,
                    "SwiftCode": "<swift>",
                    "SortCode": "<sortcode>",
                    "BankAddress": "Waterside Court, Chatham Maritime, Chatham England ME4 4RT UNITED KINGDOM",
                    "BankAddress1": "Waterside Court, Chatham Maritime",
                    "BankAddress2": "Chatham England ME4 4RT UNITED KINGDOM",
                    "Country": "GB",
                    "Type": 0,
                    "PayInReference": null
                }
            ],
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
    "AuthorisedClientModel": {
        "ClientId": "<clientid>",
        "ClientRef": "<clientref>",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<userid>",
        "AppVersion": null,
        "TokenStartDate": "2023-11-01T00:00:00",
        "TokenEndDate": "2023-12-01T00:00:00",
        "LoginTimestamp": "2023-11-21T11:07:05.7411671",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Step 3. Create a Beneficiary

There are two beneficiary types, these are:

  1. Individuals - used for transferring funds to a single person.
  2. Entities - used for transferring funds to businesses.

Depending on which type of account is being created, there may be more, or less requirements. For more information, see the table below:

NameDescriptionTypeRequired/Optional
NameThe Name attributed to the beneficiary being created. Typically, this is a business or company name.strRequired if BeneficiaryType is Entity.
SalutationThe Beneficiary's Title.strRequired if BeneficiaryType is Individual.
FirstNameThe Beneficiary's first name.strRequired if BeneficiaryType is Individual.
MiddleNameThe Beneficiary's middle name.strRequired if BeneficiaryType is Individual.
LastNameThe Beneficiary's last name.strRequired if BeneficiaryType is Individual.
ReferenceA reference can help to identify the account. E.g. "Monthly Subscription Payment".strOptional - Adding a Reference is recommended.
BeneficiaryAddress1The Beneficiary's first line of address.strRequired.
BeneficiaryAddress2The Beneficiary's second line of address.strOptional.
EmailThe Beneficiary's preferred email address.strOptional.
PhoneThe Beneficiary's preferred contact number. This can be a mobile or landline.strOptional.
BeneficiaryTypeDescribes whether the Beneficiary is an Individual or an Entity.strRequired

To create a beneficiary:

  1. Call POST - Add Beneficiary.
  2. Enter the beneficiary's bank details as shown in Step 2. In the example below, we demonstrate how to create an Individual beneficiary, based in France. The instructions assume, that the Account object from Step 2 is completed using French account details.
  3. Submit the request. A successful response returns a Value used to identify the beneficiary.

REQUEST

curl --location 'https://caxapi-test.azurewebsites.net/api/beneficiaries' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
  "Account": {
    "Country": "FR",
    "Currency": "EUR",
    "Iban": "FR1010096000509436635511H41",
  },
  "Name": "TEST France",
  "Salutation": "Mr",
  "FirstName": "John",
  "MiddleName": "",
  "LastName": "Doe",
  "Reference": "test",
  "BeneficiaryAddress1": "string",
  "BeneficiaryAddress2": "string",
  "BeneficiaryType": "Individual"
}'

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "Value": 40081,
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
    "AuthorisedClientModel": {
        "ClientId": "<ClientId>",
        "ClientRef": "<ClientRef>",
        "UserId": "<UserId>",
        "TokenStartDate": "2023-11-06T10:06:28.1175216",
        "TokenEndDate": "2024-02-15T12:17:37.4982696",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<UserId>",
        "AppVersion": null,
        "TokenStartDate": "2024-01-10T00:00:00",
        "TokenEndDate": "2024-02-09T00:00:00",
        "LoginTimestamp": "2024-01-11T17:52:09.8217665",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Create a Beneficiary for a Sub-Account

Beneficiaries can be created for Sub-Accounts via the POST - Create a Beneficiaryendpoint, and by entering the IdentityNumber in the Headers to identify the Sub-Account. To find the IdentityNumber for a specific Sub-Account, call Get - Sub-Account details.

Check for Existing Beneficiaries

To confirm whether a beneficiary already exists on the account:

  1. Call POST - Check for Existing Beneficiary.
  2. Enter the relevant details in the request body.
    1. IF searching for a Beneficiary by their bank details, leave everything but the BeneficiaryType blank. i.e. Salutation, FirstName, LastName, BeneficiaryAddress1, BeneficiaryAddress2, Email, and Phone can all be left blank.

In the example below, we search for the beneficiary we created in Step 3:

πŸ“˜

Note

In this request, the BeneficiaryType must be set to "0" for Entity OR"1" for Individual.

REQUEST

curl --location 'https://caxapi-test.azurewebsites.net/api/beneficiaries/validate' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
  "Account": {
    "Country": "FR",
    "Currency": "EUR",
    "Iban": "FR1010096000509436635511H41",
    "Swift": "{{swift}}",
    "SortCode": "null",
    "AccountNumber": "null"
  },
  "Name": "",
  "Salutation": "Mr",
  "FirstName": "John",
  "MiddleName": "",
  "LastName": "Doe",
  "Reference": "",
  "BeneficiaryAddress1": "null",
  "BeneficiaryAddress2": "null",
  "Email": "",
  "Phone": "",
  "BeneficiaryType": "1"
}'

If the beneficiary is on the account, the response returns a Value to confirm this beneficiary already exists. If the beneficiary is noton the account, the response comes back empty:

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "Value": 40081,
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
    "AuthorisedClientModel": {
        "ClientId": "<ClientId>",
        "ClientRef": "<ClientRef>",
        "UserId": "<UserId>",
        "TokenStartDate": "2023-11-06T10:06:28.1175216",
        "TokenEndDate": "2024-02-15T12:17:37.4982696",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<UserId>",
        "AppVersion": null,
        "TokenStartDate": "2024-01-10T00:00:00",
        "TokenEndDate": "2024-02-09T00:00:00",
        "LoginTimestamp": "2024-01-11T17:52:09.8217665",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Find Beneficiary

There are three ways to find a beneficiary:

  1. GET Beneficiaries - List all Lists all the beneficiaries.
  2. GET Beneficiaries - by Id Get a beneficiary's details by their Id.
  3. GET Beneficiaries - by Currency CodeLists all the beneficiaries for a given currency code.

Edit Beneficiary

Information on a beneficiary account may need to be edited. In such cases, the PUT - Edit Beneficiary Details endpoint can be called, enabling a beneficiary's details to be edited such as, First name, Address, Phone details, etc. Additionally, a beneficiary type can also be changed from Individual to Entity and vice-versa.

Bank details however, cannot be changed for a beneficiary.

Delete Beneficiary

A beneficiary can only be deleted if no transactions are carried out on the account. To delete a beneficiary call DEL - Delete Beneficiary.

Step 4. Create a Payment Request for a Beneficiary

Payments can be made to beneficiaries on specified dates - provided they are ordinary business days. Additionally, the beneficiary must have their registered details in the currency being transferred, or else an error is returned.

Example: Beneficiary has an EUR account in France, but the payment request is made in GBP, this type of request results in an error.

To create a payment:

  1. Call POST - Create a Payment.
  2. Enter the details outlined in the Payment Request details table below.
  3. If the request is carried out correctly, the transfer Id is created and the status is set to Pending. For a full list of statuses, check the Transfer Status table on this page.

Payment Request Details

NameDescription
BeneficiaryIdThe Id assigned to the Beneficiary when it's first created. If unsure, check the Find Beneficiary section on this page.
BuyCurrencyThe currency the payment is being made in.
BuyAmountThe amount the payment is being made in.
PayAwayDateThe date the payment is scheduled for. This must be a business day.
PayAwayReferenceA reference for the transfer being made.
FeeCurrencyThe currency the fee should be charged in.
FeeThe amount charged for the transaction being made. This value is configurable.
TransferReasonThere are a number of transfer reasons available listed in the Transfer Reasons section of this page.
PurposeCodeA unique code that must be provided for beneficiary's within certain countries. See Purpose Codes for more information.

Transfer Reasons

Transfer reasons are a compliance requirement and must be set to carry out the payment transfer successfully.

ValueDescription
1Emigration
2Gifting - Gifting or loaning money to family member.
3Inheritance
4Investments - Making or selling overseas investments.
5Expenditure - Moving money between own accounts for general expenditure.
6Expenses - Overseas medical expenses.
7HolidayExpenses - Paying for holiday accommodation or other holiday related expenses.
8BillPays - Paying overseas bills.
9Taxes - Paying overseas taxes.
10Property - Property purchase/sale.
11Pension - Receiving pension.
12Employment - Receiving salary for overseas employment.
13Weddings
14Others

An example request is shown below:

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/transfers/pending/add' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--data '{
  "BeneficiaryId": 12345,
  "BuyCurrency": "EUR",
  "BuyAmount": 10,
  "PayAwayDate": "2023-02-17",
  "PayAwayReference": "Expenses",
  "FeeCurrency": "GBP",
  "Fee": 0,
  "TransferReason":4
}'

A successful response is shown below. The Value created as a result, is the corresponding transfer Id, which can be used in searches to retrieve details pertaining to the specific transfer:

RESPONSE

{
    "Content": {
        "Model": {
            "Value": 78275,
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
}