Bureau API - Submission from Job
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/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 defined Bureau Job
Step 1 - Creating a Bureau Job
Creating a Bureau Job is performed using a POST request to the Jobs endpoint, with the Job Name, Group Name, and whether the job requires the submission files to be deleted following submission.
Call type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/Jobs
Request:
Copy
{
"name": "Submission Job",
"deleteSourceFiles": false,
"groupId": "e45a26c0-9c46-457f-961d-9eafc249e380"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
"jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/"
}
Returned in the request is the URL that is used to view and modify the Job from this point onwards.
Step 2 - Adding Job Details to a Job
Job Details are the references to individual files or folders that are used to build a submission. Using the “jobId” returned in the response in Step 1, details are added to the job using a POST request.
The default import schema available are Legacy and Standard18, but the name of a known Mapping can also be used to import the file.
If the filename is known, or the folder containing the filename is used, these can be passed in as the filename in the request to create Job Details.
Call type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-jobs/add-detail
Request:
{
"jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
"importSchema": "Standard18",
"fileName": "MyFile*.txt",
"customerReference": "IMPORTCUST"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
"jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/",
"jobDetailId": "8aedef92-2d3d-4570-b346-44ebad6f1a80",
"jobDetailUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/details/8aedef92-2d3d-4570-b346-44ebad6f1a80"
}
Step 2a - Getting a list of available files
To get a list of available files for use within Bureau:
Call Type: GET
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-jobs/files
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"paths": [
"/folder/",
"/folder/file1.csv",
"/folder/file2.csv",
"yourfile.csv"
],
"count": 0,
"currentPage": 0,
"totalPages": 0
}
Step 2b - Getting a list of available mappings
To get a list of available mappings for use within Bureau:
Call Type: GET
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-jobs/mappings
Response:
[
{
"id": "[Mapping ID]",
"paygateId": "[YOUR PAYGATE ID]",
"title": "Mapping 1"
},
{
"id": "[Mapping ID]",
"paygateId": "[YOUR PAYGATE ID]",
"title": "Mapping 2"
}
]
Step 3 - Creating a Submission from a Job
Once a submission has been built, it can turned into a Submission by posting to the jobId from Step 1, providing a submission reference, contra narrative and processing date. This call triggers the process that Imports files from a Job, Processes and Validates them:
Call Type: POST
Url: https://api.paygateservicedemo.com/bureau_publicapi/api/v1/bureau-jobs/createsubmission
Request:
{
"submissionId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
"submissionReference": "MONTHLYSUB01",
"contraNarrative": "CONTRA",
"paymentDate": "2024/08/20"
}
Response:
{
"success": true,
"messages": [
"Operation Successful"
],
"submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"taskProgressUrl": "/api/v1/bureau-jobs/bureau-job-progress?submissionId=ed797670-6a5e-48ca-a9f8-c1011705dc9f"
The response contains a task progress URL which is used to track how the Job to Submission process is going.
The Submission URL from the Response, as well as being used for validation and sending to BACS, can also be used to modify the submission as described in the tutorial to Build a submission manually.
Job Progress
Before a Job Submission can be edited or progressed, the import process needs to be completed. Using the Progress URL from the previous section, the current state of the Job can be viewed:
Call Type: GET
Example Response:
{
"complete": true,
"error": false,
"messages": [
"File1.csv: Imported 100 record(s)",
"File2.csv: Imported 100 record(s)",
"File3.csv: Imported 100 record(s)"
],
"importPercentage": 100,
"processPercentage": 100,
"validationPercentage": 100,
"submissionId": "b9a3116f-e4ea-45bb-8c8a-39e2ed2e0380",
"submissionUrl": "/api/v1/bureau-jobs/bureau-job-progress?submissionId=b9a3116f-e4ea-45bb-8c8a-39e2ed2e0380"
}
Once complete, progress to Step 4, or edit a submission manually.
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 id found in the response from Step 3 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, 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": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
"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",
"subType": "structuralTest",
"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"
}