Payroll & Bulk Payments
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:
- Call the
POST - Create Bulk Upload
endpoint.- If creating the Bulk Upload for a Sub-Account, add the corresponding
IdentityNumber
in the Headers.
- If creating the Bulk Upload for a Sub-Account, add the corresponding
- Enter a description of the upload.
- Select an
ExternalSource
. Each value corresponds to the file format type being uploaded.
External Source (File Format) | Value |
---|---|
Caxton | 1 |
Xero | 2 |
BACS | 5 |
CXTN Payroll | 8 |
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:
- Call
POST - Lists All Bulk Uploads
- Enter the
UploadRecordId
for the bulk upload to modify. - Retrieve the
Id
for the associated record to modify. - Follow Step 3a or Step 3b as required.
Step 3a. Modify a Single Entry
To modify a single entry within the bulk upload file:
- Call
PUT - Upload Association
. - Enter the
bulkPaymentUploadId
to refer to a specific bulk upload. This is also referred to as theUploadRecordId
in Step 3. - Enter the
uploadAssociationId
to associate a specific entry within the bulk upload. This is also referred to as theId
in Step 3. - Enter the
amount
,date
, andreference
accordingly.
Step 3b. Include or Exclude a Single Entry
To prevent a single entry on the bulk upload file from being processed:
- Call the
PUT - Include/Exclude Entry
endpoint. - Enter the
bulkPaymentUploadId
to refer to a specific bulk upload. This is also referred to as theUploadRecordId
in Step 3. - Enter the
uploadAssociationId
to associate a specific entry within the bulk upload. This is also referred to as theId
in Step 3. - Set to
true
orfalse
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:
- Call
PUT - Process Upload
. - Set the Status code value
"0"
. - 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:
- Call the
PUT - Process Upload
endpoint. - Set status value to
"4"
to submit the file.- Alternatively, should an upload need to be cancelled, this endpoint can also be used, but the status value must be set to
"9"
instead.
- Alternatively, should an upload need to be cancelled, this endpoint can also be used, but the status value must be set to
- 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:
Lookup Bulk Uploads by Id
To find a particular bulk upload:
- Call
GET - Lists Bulk Upload by the Id.
. - 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 8 months ago