Payments API - Create a Submission
Overview
In this tutorial, you will be guided through the steps of creating a submission through to sending the submission to BACS, all using the payment API.
This tutorial assumes that you have already set up all the prerequisites in Postman and paygate as described in the the “Getting Started” tutorial.
The payments API documentation can be found in the developer portal e.g. https://developer.paygateservice.com/api/payments/payments.html
Base URLs
There are two URLs you can use, one for your development testing and one for production. These URLs are:
- Test : https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/
- Production: https://api.paygateservice.com/bacs_publicapi/api/bacs/
For the purpose of this tutorial we will use the test URL.
Getting Started
Test the connection to the API via the following “ping” call:
https://api.paygateservicedemo.com/bacs_publicapi/api/ping
You should receive an HTTP status code of 200 following a successful request.
API Calls
The API call order is important although the API will return an error if the calls are made in the wrong order.
Get API 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.
Call type: GET
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/group
Example JSON Response:
[
{
"groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
"groupName": "BACS RFB",
"networkType": "BACS",
"groupType": 0,
"groupTypeDesc": "BACS"
},
{
"groupId": "469502ad-0789-4646-8d8c-db7fade55354",
"groupName": "FPS RFB",
"networkType": "FasterPayments",
"groupType": 4,
"groupTypeDesc": "FPS"
}
]
All Steps Required to Create a New Submission Through to Sending to BACS
Step 1 - Initialise a New Submission
The first step is to initialise a new submission as shown below.
Call type: POST
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/submission
Request:
{
"reference": "July Payments",
"groupId": "d34f764f-94e1-42fe-8eab-d69a9ad8a9f6",
"networkType": "BACS"
}
Response:
{
"id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"success": true,
"count": 1,
"message": "Created BacsSubmission record with ID b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"messageType": 0,
"messageTypeDesc": "Info"
}
Step 2 - Create Payments
Once a submission has been initialised we can add some payments to that submission. To prevent potential network issues it is advised to limit the number of payments sent in each request to 100,000. This isn’t an enforced limitation just a recommendation. Additional payments can be added to an existing submission until the submission is signed.
Call type: POST
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/payment
Request:
[
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"thirdPartyAccountName": "GEDDY LEE",
"thirdPartyAccountNumber": "10000003",
"thirdPartySortCode": "010197",
"thirdPartyAccountType": "0",
"transactionCode": "99",
"freeFormat": "0000",
"amount": 101.06,
"userReference": "BLUE JAYS TICKET"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"thirdPartyAccountName": "ALEX LIFESON",
"thirdPartyAccountNumber": "10000011",
"thirdPartySortCode": "010197",
"thirdPartyAccountType": "0",
"transactionCode": "99",
"freeFormat": "0000",
"amount": 200,
"userReference": "GOLF MEMBERSHIP"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"thirdPartyAccountName": "NEIL PEART",
"thirdPartyAccountNumber": "10000038",
"thirdPartySortCode": "010197",
"thirdPartyAccountType": "0",
"transactionCode": "99",
"freeFormat": "0000",
"amount": 300,
"userReference": "NEW MOTORBIKE"
}
]
Response:
{
"id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"success": true,
"count": 3,
"message": "Inserted 3 payments.",
"messageType": 0,
"messageTypeDesc": "Info"
}
Step 3 - Run Pre-submission Validation
Before a submission can be sent to BACS, all the payments must be validated e.g. sort codes must consist of 6 digits. The pre-submission validation should be carried out after all payments have been added to the submission.
Call type: POST
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/presubValidation
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583"
}
Response where pre-submission validation passes without any issues:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"result": 0,
"validationResult": "Valid",
"resultMessage": null,
"totalPresubValMessages": 0
}
There are a number of possible validation results which are “Valid”, “Warnings”, “Fixes”, “Duplicates” and “Info”.
Valid: No issues found.
Fixes: These cannot be ignored meaning that the submission cannot be saved and progressed. Example of a fix could be a sort code with only 5 digits.
Warnings: These can be ignored meaning the submission can be saved. Example of a warning could be if a sort code is not found when checking bank accounts.
Duplicates: These can be ignored and are similar to warnings. Example of a duplicate is multiple payments for the same bank account.
Info: These can be ignored and represent minor issues. Example of a info message would be where an account name was changed to upper case.
Step 4 (Optional) - Get Pre-submission Validation Messages
This step is only required if you need to see the pre-submission validation issues i.e. if the pre-submission validation result is not “Valid”.
If your company’s policy is to ignore warnings, duplicates and info messages then this step is only needed if the result is “Fixes”.
Call type: GET
Response:
[
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"fileNumber": 1,
"recordNumber": 1,
"criteriaId": "PSV/PI2 A",
"title": "Invalid transaction code",
"description": "The payment transaction code '89' is invalid for a BACS submission.",
"presubValArea": "TransactionCode",
"messageSeverity": "Fix",
"messageSeverityValue": "Fix",
"itemId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
"pkid": "c3b0cfab-e9a5-42bd-8535-99043ccc8e35"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"fileNumber": 1,
"recordNumber": 1,
"criteriaId": "PSV/PI2",
"title": "Transaction code not allowed.",
"description": "The transaction code '89' is not allowed for the Service User Number 999992.",
"presubValArea": "TransactionCode",
"messageSeverity": "Fix",
"messageSeverityValue": "Fix",
"itemId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
"pkid": "e6eff280-ad95-4048-a6eb-312a226f979e"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"fileNumber": 1,
"recordNumber": 3,
"criteriaId": "PSV/PI5 B",
"title": "Invalid third party sortcode / account number",
"description": "The third party sortcode '999197' and account number '90000038' failed a modulus check. The modulus check error is 'The supplied sort code could not be found'.",
"presubValArea": "Format",
"messageSeverity": "Warning",
"messageSeverityValue": "Warning",
"itemId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
"pkid": "62f7c01e-cabb-4078-848e-01235a3acfae"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"fileNumber": 1,
"recordNumber": 3,
"criteriaId": "PSV/PI4 A",
"title": "Invalid third party sort code",
"description": "The third party sortcode '999197' and account number '90000038' failed a modulus check. The modulus check error is 'The supplied sort code could not be found'. The third party sort code '999197' could not be found. This may indicate that the sort code is incorrect. ",
"presubValArea": "Format",
"messageSeverity": "Warning",
"messageSeverityValue": "Warning",
"itemId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
"pkid": "d7bd9237-122c-4ec4-9b50-b844021c1869"
},
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"fileNumber": 1,
"recordNumber": 1,
"criteriaId": "PSV/P16",
"title": "Submission contains illegal characters.",
"description": "The Submission contains illegal characters in the bank reference, 'Illegal Characters'. This affects every payment in your submission file. These characters will be automatically amended before submitting to BACS.",
"presubValArea": "Format",
"messageSeverity": "Info",
"messageSeverityValue": "Info",
"itemId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
"pkid": "ef6f7e0a-9c07-4f2d-a356-ba89bc5d8b5c"
}
]
Step 5 - Save Submission
Assuming that the pre-submission validation result was not “Fixes”, you can now save the submission meaning it can be signed, approved and sent to BACS.
Call type: PUT
URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/submission
NB. There a number of other options if your users have access to paygate to manually sign and approve a submission but these aren’t covered here. This example is the most common and simplest scenario. See the API documentation for more details on alternative action requests.
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583"
}
Response:
{
"id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"success": true,
"count": 1,
"message": "Submission saved",
"messageType": 0,
"messageTypeDesc": "Info"
}
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/bacs_publicapi/api/bacs/action
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"actionType": "Sign"
}
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/bacs_publicapi/api/bacs/action
Request:
{
"submissionId": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
"actionType": "Approve"
}
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/bacs_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"
}
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"
}