Documentation Powered by ReDoc

paygate.bacs.v3 (3.0)

Download OpenAPI specification:Download

Support: support@paygate.uk URL: https://paygate.uk

The Public API for paygate BACS (3.2.5). Customer needs either the BACS and/or Faster Payment API licence to make any calls to the API.

Recommended call order:

  • Create an OAuth2 token
  • GET group for list of groups which can be used by your API service account
  • POST submission to initialize submission
  • POST payment to add payments to the submission
  • POST presubvalidation to run pre-sub validation
  • GET presubvalidation to get any pre-sub messages if pre-sub validation failed
  • PUT submission to save submission
  • POST action for Sign
  • POST action for Approve
  • POST action for Send
  • GET submission to get submission summary report XML or HTML

Authentication

API_Key_1

Security Scheme Type OAuth2

Get submission summary

Get submission summary after sending submission to Vocalink. The response can be the submission summary either as XML or HTML.

query Parameters
submissionId
required
string <uuid>

ID of submission

format
string

Omit parameter for XML. Options if set are xml and html.

Responses

Response samples

Content type
application/json
Example
Submission summary data returned by BACS as XML
Submission summary data returned by BACS as XML
Submission summary data returned by BACS as HTML
{
  • "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"
}

Save submission

Save submission and optionally create a signing action.

Request Body schema: application/json

Example 1 where no actions will be created; all processing will be done by other API calls. Example 2 where signing action will be created.

submissionId
required
string <uuid>

The submission ID.

actionType
string

Sign, Approve or Send. This is required for the sign, approve and send requests. If this is included with the PUT Save Submission request it will be ignored.

subType
string

Vocalink submission type e.g. live, structuralTest. BACS has an extra option, fullTest. This is only required for a direct group "Send" action or for an indirect group "Approve" action. If this is included in the request for any other call it will be ignored.

createSignAction
boolean

True if the API should create a sign action when saving the submission via submission PUT.

createApproveAction
boolean

True if the API should create an approve action after signing with the API or after a user processes a sign action for a submission created by the API.

createSendAction
boolean

True if the API should create a send action after approving with the API or after a user processes an approve action for a submission created by the API.

callbackUri
string

Customer callback URI that the BACS API will send acknowledgement to after a manual process has been completed.

Responses

Request samples

Content type
application/json
Example
Example 1
Example 1
Example 2
{
  • "submissionId": "1949ed10-46e3-4513-8787-2f3a412335ff"
}

Response samples

Content type
application/json
{
  • "id": "3540ae61-e666-4c6d-9cdc-aaf53c863c2c",
  • "success": true,
  • "count": 1,
  • "message": "Submission saved",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Create a new submission

Initialize a new submission

Request Body schema: application/json

Request to create a new submission. This will return the new submission ID which the caller must use when adding payments to the submission.

For BACS "3-day" submissions paygate sends the submission data to BACS on day 1. The payments are processed on the day before the requested payment date i.e. day 2. The payments will be sent/received on the requested payment date i.e. day 3.

If "paymentDate" is not sent in the request, the payments will be sent/received by BACS on the next available payment date.

reference
required
string [ 1 .. 150 ] characters

Submission reference

contraNarrative
string <= 50 characters

Optional submission contra narrative

groupId
required
string <uuid>

Group linked to the submission

networkType
required
string

Valid values are BACS or FasterPayments

paymentDate
string <date>

Optional date payments will be made. If not set then the next payment date will be used.

Responses

Request samples

Content type
application/json
Example
Simplest request
Simplest request
With optional contra narrative
With optional payment date
{
  • "reference": "July Payments",
  • "groupId": "d34f764f-94e1-42fe-8eab-d69a9ad8a9f6",
  • "networkType": "BACS"
}

Response samples

Content type
application/json
{
  • "id": "1949ed10-46e3-4513-8787-2f3a412335ff",
  • "success": true,
  • "count": 1,
  • "message": "Created BacsSubmission record with ID 1949ed10-46e3-4513-8787-2f3a412335ff",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Get payments

To return all payments only add the submission ID to the query string. E.g. https://api.paygate.tbc/api/bacs/payment?submissionId=b1d33536-fd3e-491f-b1dd-efa9c10c4583

To prevent potential network issues it is advised to limit the number of payments request in each request to 100,000. This isn't an enforced limitation just a recommendation.

To determine the number of payments in the submission use the "payment/count" request.

To return a subset of payments add recordNumberFrom and/or recordNumberTo to the query string.

E.g. The following will return payments where the recordNumber is between 101 and 200: https://api.paygate.tbc/api/bacs/payment?submissionId=b1d33536-fd3e-491f-b1dd-efa9c10c4583&recordNumberFrom=101&recordNumberTo=200

The following will return payments where the recordNumber is at least 50: https://api.paygate.tbc/api/bacs/payment?submissionId=b1d33536-fd3e-491f-b1dd-efa9c10c4583&recordNumberFrom=50

The following will return payments where the max recordNumber is 100: https://api.paygate.tbc/api/bacs/payment?submissionId=b1d33536-fd3e-491f-b1dd-efa9c10c4583&recordNumberTo=100

query Parameters
submissionId
required
string <uuid>
recordNumberFrom
integer

Determines first record number of returned payments

recordNumberTo
integer

Determines last record number of returned payments

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Create payments

Add payments to a 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.

The "processingDate" property is optional and if present must be a valid date in the format yyyy-MM-dd. A "processingDate" of "0001-01-01" i.e. the .NET DateTime.MinValue will be ignored by the API and treated as a payment without a processing date.

Request Body schema: application/json

Pass an array of PaymentRequest objects in the JSON request.

submissionId
required
string <uuid>

ID of the submission the payment belongs to. This ID will have been returned after creating a new submission.

thirdPartyAccountName
required
string [ 1 .. 50 ] characters

Account name of third party regardless of whether they are beneficiary of a credit payment or if a payment is requested from them. While up to 50 characters can be saved in the database only the first 18 characters will be sent to BACS.

thirdPartyAccountNumber
required
string 8 characters

Third party account number.

thirdPartySortCode
required
string 6 characters

Third party sort code.

thirdPartyAccountType
required
string 1 characters

Should be "0" for a normal bank account. Can vary for building society accounts. Must be between 0 and 9.

transactionCode
required
string 2 characters

Debit codes: 01, 17, 18, 19. Credit codes: 99, Z4, Z5. DDI codes: 0N, 0C, 0S. Bank grade codes: RA, U1, U7, U8, U9.

freeFormat
string [ 0 .. 4 ] characters

Usually set to "0000" or 4 spaces. Can also be used for RTI data e.g. "/YYZ"

amount
required
number >= 0

The payment amount is in pounds and pence although the pence is optional. E.g. 100, 100.00 and 100.99 are all valid amounts.

userReference
string [ 0 .. 50 ] characters

User reference field which is optional when transaction code is 99 otherwise it is mandatory. E.g. "COUNCIL TAX". While up to 50 characters can be saved in the database only the first 18 characters will be sent to BACS.

processingDate
string <date> 10 characters

Optional processing date. Only need to set a date if payments in a submission can be processed on different days. The "processingDate" property is optional and if present must be a valid date in the format yyyy-MM-dd. A "processingDate" of "0001-01-01" i.e. the .NET DateTime.MinValue will be ignored by the API and treated as a payment without a processing date.

Responses

Request samples

Content type
application/json
Example
Example adding 3 payments
Example adding 3 payments
Payments with processing dates
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
  • "success": true,
  • "count": 3,
  • "message": "Inserted 3 payments.",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Update a payment

Update an existing payment.

Request Body schema: application/json

The PaymentUpdateRequest object is similar to the PaymentRequest POST object but there are a limited number of properties which can be updated.

submissionId
required
string <uuid>

ID of the submission the payment belongs to. This ID will have been returned after creating a new submission.

recordNumber
required
integer <int32>

Each payment gets a unique record number when it's created. This is needed to identify the payment to be updated. Call GET payments to get payment record numbers.

thirdPartyAccountName
required
string [ 1 .. 50 ] characters

Account name of third party regardless of whether they are beneficiary of a credit payment or if a payment is requested from them. While up to 50 characters can be saved in the database only the first 18 characters will be sent to BACS.

thirdPartyAccountNumber
required
string 8 characters

Third party account number.

thirdPartySortCode
required
string 6 characters

Third party sort code.

transactionCode
required
string 2 characters

Debit codes: 01, 17, 18, 19. Credit codes: 99, Z4, Z5. DDI codes: 0N, 0C, 0S. Bank grade codes: RA, U1, U7, U8, U9.

amount
required
number >= 0

The payment amount is in pounds and pence although the pence is optional. E.g. 100, 100.00 and 100.99 are all valid amounts.

userReference
string [ 0 .. 50 ] characters

User reference field which is optional when transaction code is 99 otherwise it is mandatory. E.g. "COUNCIL TAX". While up to 50 characters can be saved in the database only the first 18 characters will be sent to BACS.

processingDate
string <date> 10 characters

Optional processing date. Only need to set a date if payments in a submission can be processed on different days.

The "processingDate" property is optional and if present must be a valid date in the format yyyy-MM-dd.

A "processingDate" of "0001-01-01" i.e. the .NET DateTime.MinValue will be ignored by the API and treated as a payment without a processing date.

A "processingDate" of "" will result in an error similar to "Error converting value {null} to type 'System.DateTime'. Path 'processingDate', line 10, position 28.".

Responses

Request samples

Content type
application/json
Example
Updated payment record
Updated payment record
Update payment record with a processing date
{
  • "submissionId": "046d67fe-efd8-4f0c-b03c-75d70359436d",
  • "recordNumber": 3,
  • "thirdPartyAccountName": "NEIL PEART",
  • "thirdPartyAccountNumber": "10000038",
  • "thirdPartySortCode": "010197",
  • "transactionCode": "99",
  • "amount": 303.03,
  • "userReference": "NEW MOTORBIKE 2"
}

Response samples

Content type
application/json
{
  • "id": "6d873644-ce87-4b2b-ad8f-bdac5beb6d69",
  • "success": true,
  • "count": 1,
  • "message": "Payment with submission Id 6d873644-ce87-4b2b-ad8f-bdac5beb6d69 and record number 3 was updated.",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Delete a payment

Delete a payment from a submission.

E.g. https://testbacs.paygate.test/api/bacs/payment?submissionId=b1d33536-fd3e-491f-b1dd-efa9c10c4583&recordNumber=3

query Parameters
submissionId
required
string <uuid>

Submission ID

recordNumber
required
integer

Record number in the submission

Responses

Response samples

Content type
application/json
{
  • "id": "b1d33536-fd3e-491f-b1dd-efa9c10c4583",
  • "success": true,
  • "count": 1,
  • "message": "Payment with submission Id b1d33536-fd3e-491f-b1dd-efa9c10c4583 and record number 3 was deleted.",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Get pre-sub validation messages

Get pre-sub validation messages after pre-sub validation has completed.

To return all message only add the submission ID to the query string. E.g. https://api.paygate.tbc/api/bacs/presubValidation?submissionid=89e74746-9c69-4d04-af4a-b0ffc083f86e

To determine the number of pre-sub validation messages for the submission use the "presubValidation/count" request.

To return a subset of messages add messageFrom and/or messageTo to the query string. NB. A payment can generate multiple validation messages which is why the optional parameters are "messageFrom" and "messageTo" rather than "recordNumberFrom" and "recordNumberTo".

E.g. The following will skip the first 100 message and return the next 100 messages: https://api.paygate.tbc/api/bacs/presubValidation?submissionid=89e74746-9c69-4d04-af4a-b0ffc083f86e&messageFrom=101&messageTo=200

The following will skip the first 49 messages and return all other messages: https://api.paygate.tbc/api/bacs/presubValidation?submissionid=89e74746-9c69-4d04-af4a-b0ffc083f86e&messageFrom=50

The following will return the first 200 messages: https://api.paygate.tbc/api/bacs/presubValidation?submissionid=89e74746-9c69-4d04-af4a-b0ffc083f86e&messageTo=200

To only return "Fixes" the query string could be: https://api.paygate.tbc/api/bacs/presubValidation?submissionid=89e74746-9c69-4d04-af4a-b0ffc083f86e&messageSeverity=Fix

query Parameters
submissionId
required
string <uuid>

ID of the submission the messages belongs to.

messageSeverity
string
Enum: "Info" "Duplicate" "Warning" "Fix"

If parameter not provided then messages for all severity options returned with the most severe messages, i.e. Fixes, returned first.

messageFrom
integer

Determines first pre-sub val message to be returned

messageTo
integer

Determines last pre-sub val message to be returned

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Run pre-sub validation

Run pre-sub validation.

Request Body schema: application/json

Only the submission ID is required at present.

submissionId
required
string <uuid>

The submission ID

Responses

Request samples

Content type
application/json
{
  • "submissionId": "477457f6-13f5-45f3-8c5d-5fae803adc8c"
}

Response samples

Content type
application/json
Example
Pre-sub val passed without issues
Pre-sub val passed without issues
Pre-sub val failed
{
  • "submissionId": "efdb4289-d331-4bfd-8370-feb1d4f763a1",
  • "result": 0,
  • "validationResult": "Valid",
  • "resultMessage": null,
  • "totalPresubValMessages": 0
}

Get task progress

Monitor progress of potentially long running tasks such as pre-sub validation. Progress will be from 0 to 100 and returned in the "Count" property.

query Parameters
submissionId
required
string <uuid>

Submission ID of running task

Responses

Response samples

Content type
application/json
{
  • "id": "3540ae61-e666-4c6d-9cdc-aaf53c863c2c",
  • "success": true,
  • "count": 75,
  • "message": "",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Get groups

Get list of groups the Service Account can use to create a submission or download reports.

query Parameters
groupRole
string

Optional parameter. If parameter is missing it defaults to "create". The only allowed group roles are "create" and "collectReports" or any casing variant of these.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get BACS processing dates

Return ProcessingDateResponse object containing collection of non-processing dates, next processing date, min and max payment dates. This is only relevant for BACS submissions. Faster payment submissions are always processed "today".

Responses

Response samples

Content type
application/json
{
  • "nonProcessingDatesISO": [
    ],
  • "nonProcessingDates": [
    ],
  • "nextProcessingDateISO": "2021-08-27T00:00:00+01:00",
  • "nextProcessingDate": "27/08/2021",
  • "minPaymentDateISO": "2021-08-31T00:00:00+01:00",
  • "minPaymentDate": "31/08/2021",
  • "maxPaymentDateISO": "2021-09-28T00:00:00+01:00",
  • "maxPaymentDate": "28/09/2021",
  • "maxProcessingDateISO": "2021-09-27T00:00:00+01:00",
  • "maxProcessingDate": "27/09/2021"
}

Get current status of a submission

Get current status of a submission

query Parameters
submissionId
required
string <uuid>

ID of the submission

Responses

Response samples

Content type
application/json
Example
Action exists
Action exists
No action
{
  • "id": "81872cd1-44c6-4b1b-a21a-eb4c372e5b40",
  • "success": true,
  • "count": 1,
  • "message": "Sign",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Sign, approve or send a submission

Sign, approve or send a submission

Request Body schema: application/json

There are different possible "workflow" combinations.

  1. Sign, approve and send actions are all carried out via calls to the API.
  2. The submission needs to be approved manually by a user. See example "Sign submission, manual approval". After a manual approval, paygate can send a callback to a customer endpoint if one has been registered. This would allow the customer application to create the "Send" submission request. Alternatively, the customer application can poll to check whether the submission has been approved. This can be done by making the call to "Send" a submission. This will fail if the submission hasn't been approved yet.
  3. The submission needs to be approved and sent manually by a user. See example "Sign submission, manual approval and send".

Callback Process: The payload sent to the customer endpoint is signed using the same API key used to create the OAuth 2.0 token used to access the BACS API. The signature hash is sent in the headers. The endpoint can use the API key to verify that the payload has originated from paygate.

A customer endpoint example which includes payload verification can be found at https://github.com/paygateuk/WebhookClient

submissionId
required
string <uuid>

The submission ID.

actionType
string

Sign, Approve or Send. This is required for the sign, approve and send requests. If this is included with the PUT Save Submission request it will be ignored.

subType
string

Vocalink submission type e.g. live, structuralTest. BACS has an extra option, fullTest. This is only required for a direct group "Send" action or for an indirect group "Approve" action. If this is included in the request for any other call it will be ignored.

createSignAction
boolean

True if the API should create a sign action when saving the submission via submission PUT.

createApproveAction
boolean

True if the API should create an approve action after signing with the API or after a user processes a sign action for a submission created by the API.

createSendAction
boolean

True if the API should create a send action after approving with the API or after a user processes an approve action for a submission created by the API.

callbackUri
string

Customer callback URI that the BACS API will send acknowledgement to after a manual process has been completed.

Responses

Request samples

Content type
application/json
Example
Call to sign the submission
Call to sign the submission
Approve the submission
Send submission
Sign submission, manual approval
Sign submission, manual approval and send
{
  • "submissionId": "37c634b0-9cda-42fc-bc35-ecacb2e2bbef",
  • "actionType": "Sign"
}

Response samples

Content type
application/json
{
  • "id": "37c634b0-9cda-42fc-bc35-ecacb2e2bbef",
  • "success": true,
  • "count": 0,
  • "message": "Submission has been signed.",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Cancel a submission

Cancel a submission

query Parameters
submissionId
required
string <uuid>

ID of the submission

cancellationReason
string

Optional reason for cancellation.

Responses

Response samples

Content type
application/json
{
  • "id": "972f5e2a-5977-4a89-9ea1-34c03360f939",
  • "success": true,
  • "count": 0,
  • "message": "Submission has been cancelled",
  • "messageType": 0,
  • "messageTypeDesc": "Info"
}

Not used

Not used

Responses

Download reports

Download reports

Request Body schema: application/json

Downloaded reports

networkType
required
string
Enum: "BACS" "FasterPayments"

BACS or FasterP ayments

reportDownloadFormat
required
string
Enum: "XML" "HTML" "CSV"

BACS report formats: XML and HTML. Faster payment report formats: XML and CSV

reportIds
required
Array of strings

Array of report download IDs

groupId
required
string <uuid>

Group ID linked to the report.

Responses

Request samples

Content type
application/json
{
  • "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  • "networkType": "BACS",
  • "reportDownloadFormat": "XML",
  • "reportIds": [
    ]
}

Response samples

Content type
application/json
Example
Example of a BACS input report as XML
Example of a BACS input report as XML
Example of a BACS input report as HTML
[
  • {
    }
]

GET Search submissions

Not used

Responses

POST Search submissions

Search submissions

Request Body schema: application/json
createdFrom
string

Submission creation date. Format is yyyy-MM-dd. If not passed to the API this will default to today's date.

createdTo
string

Submission creation date. Format is yyyy-MM-dd. If not passed to the API this will default to today's date.

groupId
string <uuid>

Used to limit returned submissions to those linked to the requested group.

reference
string

Optional submission reference search parameter

networkType
string
Enum: "BACS" "FasterPayments" "All"

If not sent to the API this will default to "All"

Responses

Request samples

Content type
application/json
{
  • "createdFrom": "2021-07-17",
  • "createdTo": "2021-07-21",
  • "reference": "",
  • "groupId": "d34f764f-94e1-42fe-8eab-d69a9ad8a9f6",
  • "networkType": "BACS"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

GET Search payments

Not used

Responses

POST Search payments

Search payments

Request Body schema: application/json

Search for payments.

groupId
string <uuid>

Used to limit returned payments to those linked to the requested group.

processingDateFrom
string

Submission processing date. Format is yyyy-MM-dd. If not passed to the API this will default to today's date.

processingDateTo
string

Submission processing date. Format is yyyy-MM-dd. If not passed to the API this will default to today's date.

thirdPartySortCode
string

Optional: Only return payments which match the sort code.

thirdPartyAccountNumber
string

Optional: Only return payments which match the account number.

thirdPartyAccountName
string

Optional: Only return payments which match the account name.

exactAccountNameSearch
boolean

When true then only return payments which match the requested thirdPartyAccountName exactly.

amountFrom
number <double> >= 0

Optional amount range search returns payments where the amount >= this value.

amountTo
number <double> >= 0

Optional amount range search returns payments where the amount <= this value.

Responses

Request samples

Content type
application/json
Example
Search payments example
Search payments example
Additional optional search parameters
{
  • "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  • "processingDateFrom": "2021-07-16",
  • "processingDateTo": "2021-07-23"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get payment count

Get number of payments in a submission.

Data returned is the number of payments in the submission e.g. 5

query Parameters
submissionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "paymentCount": 5
}

Return the processing date for the requested payment date.

Return the processing date for the requested payment date which can be in either the yyyy-MM-dd or dd/MM/yyyy format. E.g. .../processingdate/getProcessingDateFromPaymentDate?paymentDate=23/07/2021 or .../processingdate/getProcessingDateFromPaymentDate?paymentDate=2021-07-23

For a payment date of 23/07/2021, the processing date returned would be 22/07/2021

query Parameters
paymentDate
required
string
Example: paymentDate=23/07/2021

Responses

Response samples

Content type
application/json
{
  • "processingDate": "22/07/2021",
  • "processingDateISO": "2021-07-22"
}

Return the payment date for the requested processing date.

Return the payment date for the requested processing date which can be in either the yyyy-MM-dd or dd/MM/yyyy format. E.g. .../processingdate/getPaymentDateFromProcessingDate?processingDate=23/07/2021 or .../processingdate/getPaymentDateFromProcessingDate?processingDate=2021-07-23

For a processing date of Friday 23/07/2021, the payment date returned would be Monday 26/07/2021

query Parameters
processingDate
required
string
Example: processingDate=23/07/2021

Responses

Response samples

Content type
application/json
{
  • "paymentDate": "26/07/2021",
  • "paymentDateISO": "2021-07-26"
}

Not used

Not used

Responses

BACS or faster payment report list

Return BACS or faster payment report list

Request Body schema: application/json

List of returned reports matching search criteria

groupId
required
string <uuid>

Needed to login to Vocalink and set correct SUN

networkType
required
string
Enum: "BACS" "FasterPayments"

BACS or FasterP ayments

reportType
required
string
Enum: "Arrival" "Input" "ARUCS" "ARUDD" "Withdrawal" "ADDACS" "AUDDIS" "DDICAdvice" "AWACS" "GenericTest" "MessagingTest" "DCAInput" "ComponentHistory" "TestInput" "All"

Available choices depends on the network type. DCAInput is for faster payments, all others are for BACS.

reportPeriod
required
string
Enum: "CurrentDay" "Last2Days" "LastWeek" "Last2Weeks" "LastMonth" "WithinLast2Days" "WithinLast3Days" "WithinLast4Days" "WithinLast5Days"

BACS enums: CurrentDay, Last2Days, LastWeek, Last2Weeks, LastMonth. Faster Payments enums: CurrentDay, WithinLast2Days, WithinLast3Days, WithinLast4Days, WithinLast5Days

reportAccessed
required
string
Enum: "No" "Yes" "Both"

Available choices depends on the network type. Both is only relevant for Faster Payments.

Responses

Request samples

Content type
application/json
{
  • "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  • "networkType": "BACS",
  • "reportType": "Input",
  • "reportPeriod": "LastMonth",
  • "reportAccessed": "Yes"
}

Response samples

Content type
application/json
{
  • "availableReports": [
    ]
}

Get submission summary details

Get submission summary details.

query Parameters
submissionId
required
string <uuid>

The submission Id GUID

Responses

Response samples

Content type
application/json
{
  • "submissionId": "f318cd65-db95-407e-948e-ba29429b1769",
  • "networkType": "BACS",
  • "totalRecordCount": 3,
  • "creditRecordCount": 3,
  • "debitRecordCount": 0,
  • "ddiRecordCount": 0,
  • "creditContraCount": 2,
  • "debitContraCount": 0,
  • "totalValue": 600,
  • "creditValue": 600,
  • "debitValue": 0,
  • "creditContraValue": 600,
  • "debitContraValue": 0,
  • "serviceUserNumber": "999992",
  • "workCode": "4 MULTI",
  • "contraNarrative": "",
  • "processingDate": "23/08/2021",
  • "submissionDate": "19/08/2021"
}

GET Standard18

Standard18 is the fixed length file format that is sent to BACS and Faster Payments containing the payment information in the submission. This API call returns the Standard18 for the requested submission.

query Parameters
submissionId
required
string <uuid>

The submission Id GUID

Responses

Response samples

Content type
text/plain
{
  "standard18": "VOL1004424                               999992                                1<PaymentFileHeader fileSequenceNumber=\"0001\" fileIdentifier=\"A999992S  1999992\" bodyFormat=\"STD18\" />HDR1A999992S  199999200442400010001       22042 220920000000                    HDR2F0200000100                                   00                            UHL1 22045999999    000000001 DAILY  260                                        0101971000000309901000412345679000000000010000ILLEGAL CHARACTERSBLUE JAYS TICKET  GEDDY LEE         0101971000001109901000412345679000000000020000ILLEGAL CHARACTERSGOLF MEMBERSHIP   ALEX LIFESON      0101971000003809901000412345679000000000030000ILLEGAL CHARACTERSNEW MOTORBIKE     NEIL PEART        0100041234567901701000412345679000000000060000ILLEGAL CHARACTERSCONTRA            ILLEGAL CHARACTERSEOF1A999992S  199999200442400010001       22042 220920                          EOF2F0200000100                                   00                            UTL10000000060000000000006000000000010000003        0000000                     "
}

GET ping

Enables the caller to test their connection to the API without needing to create an OAuth2.0 token.

Responses

Get pre-sub validation message count

Get number of pre-sub validation messages for a submission.

Data returned is the number of pre-sub validation messages for the submission e.g. 5

query Parameters
submissionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "messageCount": 4
}