Bureau API - Build Submission Manually
Base URLs
There are two URLs that used, for development, it is recommeded that the Test URL is used. These URLs are:
- Test : https://api.paygateservicedemo.com/bureau_publicapi/api/bacs/
- Production: https://api.paygateservice.com/bureau_publicapi/api/bacs/
This tutorial will use the test URL.
A complete list of operations can be found on the API document:
Prerequisites
Bureau API Submissions requires an available Bureau Group (which holds the Bureau SUN used for the submission) and at least one Bureau Customer, which holds the originating account details for blocks in a submission.
Groups
You will need a group id to create a new submission. This call will return the groups that can be used by the API to create a submission. This step is optional if you already know the group id to use for the submission. Ensure that a group with a “groupTypeDesc” of “Bureau” or “FPS Bureau” is used.
Call type: GET
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/group
Example JSON Response:
[
{
"groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
"groupName": "My Submission Group",
"networkType": "BACS",
"groupType": 1,
"groupTypeDesc": "Bureau"
}
]
Customers
Bureau Customers can be created using a POST call to the Customers endpoint:
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-customers
Request:
{
"name": "John Smith Business",
"contactFirstName": "John",
"contactSurname": "Smith",
"customerAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
},
"telephone": "01234 567890",
"telephone2": "01234 567890",
"websiteUrl": "https://www.johnsmithsbusiness.fake/",
"emailAddress": "johnsmith@johnsmithsbusiness.fake",
"serviceUserNumber": "100000",
"paymentLimit": 10,
"submissionLimit": 10.5,
"deleted": false,
"contraNarrative": "CONTRA",
"bankName": "Trusted Bank Plc.",
"sortCode": "101010",
"accountNumber": "10101010",
"createdDate": "2019-08-24T14:15:22Z",
"modifiedDate": "2019-08-24T14:15:22Z",
"defaultImportSchema": "Mapping",
"defaultImportMapping": "Your Mapping",
"defaultImportFilename": "Filename.txt",
"tags": "TAG1",
"bankReference": "SMITH123",
"bankAddress": {
"line1": "15 High Street",
"line2": "Fictional Business Park",
"line3": "Fictional Area",
"line4": "Fictional Area",
"locality": "Fictional Locality",
"postcode": "AA1 1AA",
"town": "Fake Town",
"county": "Fake County"
}
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"customerUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
"notesUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
"jobsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
"submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
}
Sending a Submission using data Added Manually
Step 1 - Initialise a Bureau Submission
Creating a Bureau Submission manually requires the API call shown below.
Call type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions
Request:
{
"submissionReference": "MYSUBMISSION",
"contraNarrative": "CONTRA",
"paymentDate": "2024/08/20",
"groupId": "e45a26c0-9c46-457f-961d-9eafc249e380"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}
The submission Url provided in the response message is used to build the submission from this point onwards.
Step 2 - Building the Submission
Using the submission ID returned in Step 1, payment blocks and transaction records (payments, credits or direct debit instructions) can be added to the submission.
Transaction records are held in “blocks” which have the necessary details such as Customer Reference (assigning the originating bank account), payment date (if different from the main submission) and a collection of transaction records.
Adding a block requires a POST request to the submissionUrl returned in step 1, with an additional Uri component of “blocks”. The request model can contain transaction records at the point of creation, or they can be added to afterwards.
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/add-block
Request:
{
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"contraNarrative": "CONTRA",
"paymentDate": "2024/10/23",
"customerReference": "YOURCUST001",
"records": [
{
"amount": 10.5,
"processingDate": "2024/08/22",
"accountName": "Mr Ollie Reeder",
"accountNumber": 342391,
"sortCode": 5349,
"transactionCode": 17,
"userReference": "P4YM3NT123"
}
]
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"blockNumber": 1,
"blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1"
}
Step 3 - Adding additional transaction records to the submission
Using the submission ID and block number returned in the response from Step 2, it is possible to add additional records to the block as an array of records
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/add-records
{
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"blockNumber": 1,
"records": [
{
"amount": 10.5,
"paymentDate": "2024/08/22",
"accountName": "Mr Malcom Tucker",
"accountNumber": "34119134",
"sortCode": "534934",
"transactionCode": "17",
"userReference": "P4YM3NT125"
},
{
"amount": 10.5,
"paymentDate": "2024/08/22",
"accountName": "Mr Peter Manion",
"accountNumber": "34339134",
"sortCode": "534942",
"transactionCode": "17",
"userReference": "P4YM3NT126"
},
{
"amount": 10.5,
"paymentDate": "2024/08/22",
"accountName": "Mr Glenn Cullen",
"accountNumber": "23239122",
"sortCode": "534911",
"transactionCode": "17",
"userReference": "P4YM3NT127"
}
]
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
]
}
Step 4 - Validating the Submission
Within the Bureau API it is possible to validate either the entire submission, or individual blocks within.
Validating the whole Submission
Posting to the validate API endpoint will trigger the validation the entire submission according to BACS presubmission validation rules. It is possible to pass an optional callback URL so that the response can be passed to an endpoint defined by the calling application or user.
The response returned by the validation call includes a “taskProgressUrl” that can be queried to learn the validation progress.
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/validate
Request:
{
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"callBackUrl": "http://endpoint.yoursite.com/expectedresult"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"taskProgressUrl": "/api/v1/bureau-submissions/validation-progress?submissionId=ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}
Validate a single block
Using the submission Url found in the response from Step 1 with “/blocks/” and the block number appended to it (see example URL below) a single block can be validated according to BACS presubmission validation rules. It is possible to pass an optional callback URL so that the response can be passed to an endpoint defined by the calling application or user.
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/validate-block
Request:
{
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"blockNumber": 1,
"callBackUrl": "http://endpoint.yoursite.com/expectedresult"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"taskProgressUrl": "/api/v1/bureau-submissions/validation-progress?submissionId=ed797670-6a5e-48ca-a9f8-c1011705dc9f&blockNumber=1"
}
Once validated, performing a Http GET API call to the validation summary endpoint will return validation messages for the submission.
Call Type: GET
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/validation-summary
Response:
{
"bureauSubmissionStatus": "Open",
"error": true,
"errorMessage": "string",
"numberOfDuplicates": 0,
"numberOfMessages": 0,
"numberOfMustFix": 0,
"numberOfWarnings": 0,
"percentComplete": 0,
"submissionId": "string",
"validationMessages": [
{
"submissionId": "string",
"fileNumber": 0,
"recordNumber": 0,
"criteriaId": "string",
"title": "string",
"description": "string",
"presubValArea": "string",
"messageSeverity": "string",
"messageSeverityValue": "Info",
"itemId": "string",
"pkid": "string"
}
],
"totalRecords": 0
}
Validation Progress
Performaing a GET request to the “validation-progress” endpoint will show details of how the validation of the submission are progressing. Validation can take a while, so querying the endpoint every few seconds is the advised approach.
Call Type: GET
Response:
{
"id": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"progress": 100,
"message": "Complete",
"userId": "8f939e23-6ded-434d-812d-be808619e64a"
}
Step 5 - Submitting
Once a submission has been built and validated, it can be entered into the process that sends it to BACS (or Faster Payments).
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-submissions/start
Request:
{
"submissionId": "643064ba-6a30-433e-ac9d-08d3dd121862",
"callBackUrl": "http://endpoint.yoursite.com/expectedresult"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"submissionUrl": "/api/bacs/action/?ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}
From this point, the Submission can be completed using the BACS API.
Step 6 - Sign Submission
In order to sign a submission via the API your group will need to be configured to use a Hardware Security Module (HSM) to sign the submission.
Creating a certificate, loading it onto the HSM and assigned the certificate to your group is beyond the scope of this tutorial.
A successful signing will create a signature of the data sent to BACS. This will also be sent to BACS along with the submission data in step 8 below.
Call type: POST
URL: https://api.paygateservicedemo.com/bureau_publicapi/api/bacs/action
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"actionType": "Sign",
"createSignAction": false,
"createApproveAction":false,
"createSendAction": false,
"callbackUri": ""
}
Response:
{
"id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"success": true,
"count": 0,
"message": "Submission has been signed.",
"messageType": 0,
"messageTypeDesc": "Info"
}
Step 7 - Approve Submission
The submission can be approved after it has been signed as shown in step 6 above.
Call type: POST
URL: https://api.paygateservicedemo.com/bureau_publicapi/api/bacs/action
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"actionType": "Approve",
"subType": "structuralTest",
"createSignAction": false,
"createApproveAction":false,
"createSendAction": false,
"callbackUri": ""
}
Response:
{
"id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"success": true,
"count": 0,
"message": "Submission has been approved.",
"messageType": 0,
"messageTypeDesc": "Info"
}
Step 8 - Send Submission
After the submission has been approved it is now finally ready to be sent to BACS!
Call type: POST
URL: https://api.paygateservicedemo.com/bureau_publicapi/api/bacs/action
Request: The “subType” options for a BACS submission are “live”, “structuralTest” and “fullTest”. Only a “live” submission will actually result in money being collected or paid out. A “structualTest” and a “fullTest” are very similar in that the payments are validated along with the overall structure of the submission data and the signature of the signed data.
{
"submissionId": "37c634b0-9cda-42fc-bc35-ecacb2e2bbef",
"actionType": "Send",
"subType": "live",
"createSignAction": false,
"createApproveAction":false,
"createSendAction": false,
"callbackUri": ""
}
Response:
{
"id": "37c634b0-9cda-42fc-bc35-ecacb2e2bbef",
"success": true,
"count": 0,
"message": "Submission has been sent.",
"messageType": 0,
"messageTypeDesc": "Info"
}
Step 9 (Optional) - Get Submission Summary
After the submission data has been sent to BACS they return a submission summary which includes whether the submission was successful or whether there were any issues.
Call type: GET
The data can be returned as either XML or HTML. If the required format is XML the “format” querystring parameter can be ignored.
Response:
{
"submissionSummaryReport": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<SubmissionResults xmlns=\"http://bacs.co.uk/submissions\"\n xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n \n submissionIdentifier=\"1626774514486T9XDURvrs\"\n status=\"complete\"\n submissionType=\"structuralTest\"\n submissionSerialNumber=\"033932\"\n submissionDateAndTime=\"Tue Jul 20 10:48:37 BST 2021\"\n submissionEarliestDate=\"2021-07-20\">\n\n \n \n\n\n <SubmittingServiceUser\n userNumber=\"999992\"\n name=\"SS - Ultra Payments 2\"/>\n\n <SubmittingContact contactIdentifier=\"DEV TEST HSM728837\"\n fullName=\"BMPL DEV TEST HSM4\" />\n\n <SigningContact contactIdentifier=\"DEV TEST HSM728837\"\n fullName=\"BMPL DEV TEST HSM4\"/>\n\n\n <PaymentFile status=\"complete\"\n index=\"1\"\n paymentFileIdentifier=\"871\"\n \n processingDay=\"2021-07-21\"\n currency=\"GBP\"\n creditRecordCount=\"3\"\n creditValueTotal=\"60100\"\n debitRecordCount=\"0\"\n debitValueTotal=\"0\"\n ddiRecordCount=\"0\"\n workCode=\"1 DAILY \">\n\n \n\n\n\n\n <OriginatingServiceUser userNumber=\"999992\"\n name=\"SS - Ultra Payments 2\"/>\n\n </PaymentFile>\n\n </SubmissionResults>\n\n\n"
}