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:

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

Name	Description	Type	Required/Optional
`Country`	The beneficiary's country. Consists of a two-letter country code as per ISO 3166-1 alpha-2.	str	Required
`Currency`	The beneficiary's currency. Consists of a three-letter currency code as per ISO 4217.	str	Required
`IBAN`	The beneficiary's IBAN. Consists of up to 34 alphanumeric characters. As per ISO 13616:2020.	str	Optional
`SWIFT`	The beneficiary's SWIFT code, as per ISO 9362:2022. Consists of 8 or 11 characters.	str	Optional
`SortCode`	The beneficiary's Sort Code. This is a six-digit number applicable to UK accounts only.	str	Required for UK accounts.
`AccountNumber`	The beneficiary's account number. This is an eight-digit number applicable to UK accounts only.	str	Required 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:

Individuals - used for transferring funds to a single person.
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:

Name	Description	Type	Required/Optional
`Name`	The Name attributed to the beneficiary being created. Typically, this is a business or company name.	str	Required if `BeneficiaryType` is `Entity`.
`Salutation`	The Beneficiary's Title.	str	Required if `BeneficiaryType` is `Individual`.
`FirstName`	The Beneficiary's first name.	str	Required if `BeneficiaryType` is `Individual`.
`MiddleName`	The Beneficiary's middle name.	str	Required if `BeneficiaryType` is `Individual`.
`LastName`	The Beneficiary's last name.	str	Required if `BeneficiaryType` is `Individual`.
`Reference`	A reference can help to identify the account. E.g. "Monthly Subscription Payment".	str	Optional - Adding a `Reference` is recommended.
`BeneficiaryAddress1`	The Beneficiary's first line of address.	str	Required.
`BeneficiaryAddress2`	The Beneficiary's second line of address.	str	Optional.
`Email`	The Beneficiary's preferred email address.	str	Optional.
`Phone`	The Beneficiary's preferred contact number. This can be a mobile or landline.	str	Optional.
`BeneficiaryType`	Describes whether the Beneficiary is an `Individual` or an `Entity`.	str	Required

To create a beneficiary:

Call POST - Add Beneficiary.
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.
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:

Call POST - Check for Existing Beneficiary.
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:

GET Beneficiaries - List all Lists all the beneficiaries.
GET Beneficiaries - by Id Get a beneficiary's details by their Id.
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:

Call POST - Create a Payment.
Enter the details outlined in the Payment Request details table below.
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

Name	Description
`BeneficiaryId`	The Id assigned to the Beneficiary when it's first created. If unsure, check the Find Beneficiary section on this page.
`BuyCurrency`	The currency the payment is being made in.
`BuyAmount`	The amount the payment is being made in.
`PayAwayDate`	The date the payment is scheduled for. This must be a business day.
`PayAwayReference`	A reference for the transfer being made.
`FeeCurrency`	The currency the fee should be charged in.
`Fee`	The amount charged for the transaction being made. This value is configurable.
`TransferReason`	There are a number of transfer reasons available listed in the Transfer Reasons section of this page.
`PurposeCode`	A 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.

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

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

Overview

Step 1. Lookup a Country's Bank Requirements

Step 2. Lookup Bank Details

Account Object

Step 3. Create a Beneficiary

Create a Beneficiary for a Sub-Account

Check for Existing Beneficiaries

📘Note

Find Beneficiary

Edit Beneficiary

Delete Beneficiary

Step 4. Create a Payment Request for a Beneficiary

Payment Request Details

Transfer Reasons

📘
Note