Guides

Payroll & Bulk Payments

Suggest Edits

Overview

The Bulk Payments API, is our solution to process multiple payments simultaneously. Using our API, Caxton can service complex business needs to withstand high volumes of payments, for as many recipients as needed, so that everyone can get paid on time in just a few clicks.

Step 1. Create a Bulk Upload

To create a bulk upload, follow these steps:

  1. Call the POST - Create Bulk Upload endpoint.
    1. If creating the Bulk Upload for a Sub-Account, add the corresponding IdentityNumber in the Headers.
  2. Enter a description of the upload.
  3. Select an ExternalSource. Each value corresponds to the file format type being uploaded.
External Source (File Format)Value
Caxton1
Xero2
BACS5
CXTN Payroll8

📘

Note

All External Source files are in CSV format.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/payments' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
  "Description": "Caxton",
  "ExternalSource": "1"
}'

RESPONSE

A successful response returns the UploadRecordId, as shown on line 4. For most file types, the ColumnFormat values are provided, and serve as a key when entering the payload in the next step. Note that, the ColumnFormat value is set to null for BACS files.

{
    "Content": {
        "Model": {
            "UploadRecordId": 1234,
            "ColumnFormat": "Action,RecipientReference,ClientRecipientReference,RecipientName,SWIFTCode,SortCode,AccountNumber,IBAN,RecipientAddress,RecipientCountry,PaymentReference,Currency,Amount,PaymentDate",
            "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-12-01T00:00:00",
        "TokenEndDate": "2023-12-31T00:00:00",
        "LoginTimestamp": "2023-12-01T14:28:43.0330362",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Step 2. Upload Bulk Payment

When the upload is successfully created, an UploadRecordId is generated and the status is set to "Pending Upload". The upload can be carried out via POST - Bulk Upload Payment . The payload required for this endpoint depends on the ColumnFormat for the corresponding External Source - as demonstrated in Step 1.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/payments/1234' \
--header 'authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "Payload": 
  
     ["Action,RecipientReference,ClientRecipientReference,RecipientName,SWIFTCode,SortCode,AccountNumber,IBAN,RecipientAddress,RecipientCountry,PaymentReference,Currency,Amount,PaymentDate",]
}'

RESPONSE

{
    "Content": {
        "Model": {
            "RecordId": 1234,
            "Description": "bacs from api",
            "FileName": "1234_Payment11-12-2023.csv",
            "DateUploaded": "2023-12-11T16:17:19.9161986Z",
            "NumberOfRecords": 2,
            "Status": "Pending upload",
            "Message": null,
            "ColumnFormat": null,
            "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-01-05T11:41:23.9495402",
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<UserId>",
        "AppVersion": "20231117.1",
        "TokenStartDate": "2023-11-21T00:00:00",
        "TokenEndDate": "2023-12-21T00:00:00",
        "LoginTimestamp": "2023-12-06T11:41:23.3089019",
        "ApiLoginType": 1,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Step 3. Modify, Include or Exclude a Record

If no changes are required, skip to Step 4, otherwise, to modify a record, you must:

  1. Call POST - Lists All Bulk Uploads
  2. Enter the UploadRecordId for the bulk upload to modify.
  3. Retrieve the Id for the associated record to modify.
  4. Follow Step 3a or Step 3b as required.

Step 3a. Modify a Single Entry

To modify a single entry within the bulk upload file:

  1. Call PUT - Upload Association .
  2. Enter the bulkPaymentUploadId to refer to a specific bulk upload. This is also referred to as the UploadRecordId in Step 3.
  3. Enter the uploadAssociationId to associate a specific entry within the bulk upload. This is also referred to as the Id in Step 3.
  4. Enter the amount, date, and reference accordingly.

Step 3b. Include or Exclude a Single Entry

To prevent a single entry on the bulk upload file from being processed:

  1. Call the PUT - Include/Exclude Entry endpoint.
  2. Enter the bulkPaymentUploadId to refer to a specific bulk upload. This is also referred to as the UploadRecordId in Step 3.
  3. Enter the uploadAssociationId to associate a specific entry within the bulk upload. This is also referred to as the Id in Step 3.
  4. Set to true or false to include or exclude that entry.

Step 4. Close the file

When a bulk upload is ready, the file must be closed first unless it's a BACS file. To do this, follow the steps below:

  1. Call PUT - Process Upload.
  2. Set the Status code value "0".
  3. A successful response closes the file and enables the upload to be submitted or cancelled in the next step.

REQUEST

curl --location --request PUT 'https://caxapi-integration.azurewebsites.net/api/payments/7019' \
--header 'Authorization: bearer <accesstoken>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
  "Status": "0"
  
}'

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-03-15T09:55:58.8508862",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Step 5. Submit or Cancel Bulk Upload

When a bulk upload is ready, the file must be submitted first, and subsequently processed. To do this, follow the steps below:

  1. Call the PUT - Process Upload endpoint.
  2. Set status value to "4" to submit the file.
    1. Alternatively, should an upload need to be cancelled, this endpoint can also be used, but the status value must be set to "9" instead.
  3. Send the request. A successful response validates the request as demonstrated in the request and response below.

REQUEST

curl --location --request PUT 'https://caxapi-integration.azurewebsites.net/api/payments/1234' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
  "Status": "4"
}'

RESPONSE

{
    "Content": {
        "Model": {
            "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-12-01T00:00:00",
        "TokenEndDate": "2023-12-31T00:00:00",
        "LoginTimestamp": "2023-12-01T14:28:43.0330362",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

🚧

Warning

Changes can only be made before the file is submitted.

List All Bulk Uploads

To list every bulk upload created on the account:

  1. Call GET - Lists All Bulk Uploads..

Lookup Bulk Uploads by Id

To find a particular bulk upload:

  1. Call GET - Lists Bulk Upload by the Id..
  2. Enter the UploadRecordId.

REQUEST

In the request below, we use the UploadRecordId created in Step 1 before being submitted, note how the Status is set to Pending Upload at this stage of the process:

curl --location 'https://caxapi-integration.azurewebsites.net/api/payments/1234' \
--header 'authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \

RESPONSE

{
    "Content": {
        "Model": {
            "RecordId": 1234,
            "Description": "BACS upload",
            "FileName": null,
            "DateUploaded": "0001-01-01T00:00:00",
            "NumberOfRecords": 0,
            "Status": "Pending upload",
            "Message": null,
            "ColumnFormat": 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-12-01T00:00:00",
        "TokenEndDate": "2023-12-31T00:00:00",
        "LoginTimestamp": "2023-12-01T14:28:43.0330362",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Updated 10 months ago