Overview

Payments can be made on behalf of customers via the Main Account by depositing funds into the corresponding Sub-account or User-Account first, and creating a beneficiary - if it hasn't already been created. To make payments, it's imperative that the country the payment is being made to is on Caxton's approved countries list.

In the following excerpts we provide some more context, and instructions on how to make a payment to Individuals and/or businesses.

Lookup Supported Countries List

To see which countries payments can be made to, call GET - List of countries and their respective bank requirements. endpoint. This endpoint shows all the countries supported and unsupported for payments by Caxton.

RESPONSE

The following shows the first result on the list:

{
    "Content": {
        "Model": {
            "Countries": {
                "Result": [
                    {
                        "ShortName": "UK",
                        "FullName": "United Kingdom",
                        "Alpha2Code": "GB",
                        "Alpha3Code": "GBR",
                        "NumericCode": "826",
                        "ForApplications": true,
                        "ForBeneficiaries": true,
                        "ForOthers": false,
                        "ForMonitor": false,
                        "ForPlaceOfBirth": false,
                        "DefaultCurrencyCode": "GBP",
                        "ISDCode": "+44",
                        "ApiStatusCode": 100,
                        "ApiStatus": "IsValid",
                        "ApiStatusDescription": "Valid Operation"
                    },
       }
}

If ForBeneficiaries is set to true, then that country is enabled to receive payments. Conversely, if set to false, payments to that country are not supported by Caxton:

{
    "Content": {
                        "ForBeneficiaries": true,
                    },

Lookup Supported Countries by Country Code

Alternatively, a specific country can be looked up to check if it is enabled for payments via the GET - Country by Country Codeendpoint. The following response is shown for 'UK', with the ForBeneficiaries value on line 11 showing as true, thereby confirming the country is enabled for payments.

RESPONSE

{
    "Content": {
        "Model": {
            "Country": {
                "ShortName": "UK",
                "FullName": "United Kingdom",
                "Alpha2Code": "GB",
                "Alpha3Code": "GBR",
                "NumericCode": "826",
                "ForApplications": true,
                "ForBeneficiaries": true,
                "ForOthers": false,
                "ForMonitor": false,
                "ForPlaceOfBirth": false,
                "DefaultCurrencyCode": "GBP",
                "ISDCode": "+44",
                "ApiStatusCode": 100,
                "ApiStatus": "IsValid",
                "ApiStatusDescription": "Valid Operation"
            },
        },
    },
}

Lookup Purpose Codes

Depending on the country, payments to specific beneficiaries may need a purpose code. The following is a list of countries where they are required. If the beneficiary you are sending a payment to is not in any of the countries below, the purpose code is not needed.

Purpose codes are needed to explain the reason for the transfer, without them, transfers may not be accepted by the beneficiary bank.

Country Code	Country
AE	Arab Emirates
BH	Bahrain
IN	India
JO	Jordan
MA	Morocco

To see a list of purpose codes for a specific country:

Call GET - Gets country purpose codes.
Enter the corresponding ccyCode as shown above.

Alternatively, to see information regarding a specific purpose code within that country:

Call GET - Gets country purpose code information.
Enter the corresponding ccyCode as shown above.
Enter the purpose code you wish to query.

Schedule a Payment to a Beneficiary

To schedule a payment to an existing beneficiary:

Call POST - Create a Payment.
Fill out the request body values.
A successful response is shown below. The Value created on line 5 as a result, is the Pending Transfer Id, which can be used in searches to retrieve details pertaining to the specific transfer. However, a TransferId value is not created until the transfer is validated by Caxton:

REQUEST

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

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "Value": 79056,
            "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"
    }
}

Search for a Pending Transfer

To list all pending transfers:

Call GET - View Pending Transfer detail by ID. This endpoint shows the transfers that are awaiting processing. Pending transfers can be cancelled before they are processed.
Enter the Pending TransferId generated when the Transfer is first created.
A successful response returns the Pending TransferId as shown on line 6 and the TransferId as shown on line 11 of the response body. The difference between the two values is that a Pending TransferId is generated when the transfer is initiated and a TransferId is generated when the transfer is validated by Caxton.

REQUEST

curl --location 'https://caxapi-test.azurewebsites.net/api/transfers/pending/79056' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--data ''

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "PendingTransfer": {
                "Id": 79056,
                "BeneficiaryId": 40081,
     				    "UserId": "<UserId>",
                "BuyCurrency": null,
                "BuyAmount": 10.00,
                "TransferId": 163253,
                "PayAwayDate": "2024-01-17T00:00:00",
                "PayAwayReference": null,
                "FeeCurrency": "GBP",
                "Fee": 0.00,
                "UserIdentities": [],
                "OpenBankingAuthId": null,
                "IsValidated": false,
                "TransferReason": "Moving money between own accounts for general expenditure",
                "AuthorisedClientId": 0,
                "TransferType": 0,
                "PurposeCode": null,
                "ApiStatusCode": 100,
                "ApiStatus": "IsValid",
                "ApiStatusDescription": "Valid Operation"
            },
            "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"
    }
}

Search for a Specific Processed Transfer

Call GET - View Transfer detail by ID. Lists completed transfers by Id.
Enter the PendingTransferId.
A successful response returns a TransferId as shown on line 6 of the response body.

REQUEST

curl --location 'https://caxapi-test.azurewebsites.net/api/transfers/163253' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--data ''

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "MoneyTransfer": {
                "Id": 163253,
                "BeneficiaryId": 40081,
                "UserId": "<UserId>",
                "BuyCcyCode": "EUR",
                "BuyAmount": 10.00,
                "Complete": true,
                "Automatic": true,
                "ExecutedDate": "2024-01-17T14:23:30.4431297",
                "PayAwayDate": "2024-01-17T00:00:00",
                "PayStatus": "Processing",
                "AccountTransactionId": 656790,
                "Cashavailable": null,
                "Authorisation": null,
                "AuthorisationStatus": null,
                "FileAccepted": null,
                "PaymentFile": null,
                "FileSent": null,
                "PaymentAccepted": null,
                "RejectionReason": null,
                "PaymentReference": "GBPGBPGBPGBPGBPGBP",
                "IsPending": false,
                "CreatedDate": "2024-01-17T14:23:30.1575654",
                "PaymentProvider": "<PaymentProvider>",
                "ComplianceStatus": 0,
                "EyeCheckStatus": 0,
                "ComplianceStatusDesc": "Awaiting",
                "IsHighRiskTransfer": false,
                "FeeCurrency": "GBP",
                "Fee": 0.00,
                "ExternalSourceId": null,
                "BeneficiaryName": "John Doe",
                "ApiStatusCode": 100,
                "ApiStatus": "IsValid",
                "ApiStatusDescription": "Valid Operation"
            },
            "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"
    }
}

Approve Payments - Sandbox Only

While using the Sandbox, payments can be manually approved to test transactions.

Change the status of a transfer

To change the status of a transfer while using the Sandbox:

Lookup the corresponding TransferId for the transaction to update by calling POST - List all Transfers and filter by "Pending".
Call {{server}}sandbox/payments-out
Enter the TransferId.
Update the TransferStatus to "Approved".

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/sandbox/payments-out' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer <access_token>' \
--data '{
  "TransferId": 164165,
  "TransferStatus": "Approved"
}'

RESPONSE

{
    "MainAccountHolderName": "<MainAccountHolderName>",
    "Content": {
        "Model": {
            "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-04-24T10:33:04.4417713",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<UserId>",
        "AppVersion": "20240322.1",
        "TokenStartDate": "2024-03-25T00:00:00",
        "TokenEndDate": "2024-04-24T00:00:00",
        "LoginTimestamp": "2024-03-25T10:33:04.410525",
        "ApiLoginType": 1,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Search all Transfers

POST - List all Transfers This endpoint shows all transfers, including those that are Cancelled, Processing, Completed, etc.

Transfer Status

Transfer statuses are used to define the stages for any given transfer. The following is a list of possible values:

Value	Description
`Transfer Started`	Transfer initiated via Caxton.
`Transfer Pending`	Account may not have enough funds to complete the transfer.
`Processing`	Transfer under review by Caxton.
`Not Authorised`	Transfer unauthorised by Caxton.
`Cancelled`	Transfers are cancelled when requested by the User.
`Completed`	Displayed when the funds reach the Beneficiary, and the transaction is considered as settled.