Bureau Submission Operations

Bureau Submission Operations

There are several operations that can be used to build reusable Bureau Submissions that can be sent to BACS or FPS.

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/v1/
• Production: https://api.paygateservice.com/bureau_publicapi/api/v1/

This tutorial will use the test URL.

A complete list of operations can be found on the API document:

https://api.paygateservicedemo.com/bureau_publicapi/api/docs/index.html?url=/bureau_publicapi/api/docs/v1/swagger.json

Get Submissions

The user can retrieve a collection of Bureau Submissions that have not been submitted by querying the endpoint below.

HTTP GET
/bureau-submissions/

A collection of Submissions is returned.

Example Response:

{
    "submissions": [
        {
            "submissionId": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
            "submissionUrl": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
            "submissionReference": "MONTHLYSUB123",
            "job": "Monthly Job",
            "group": "My Submission Group",
            "created": "2019-08-24T14:15:22Z",
            "lastModification": "2019-08-24T14:15:22Z",
            "createdBy": "Malcom Tucker",
            "status": "Open",
            "locked": false,
            "editingUser": "Terri Coverley"
        }
    ]
}

Create Bureau Submission

A Bureau Submission can be created by performing a HTTP POST operation to the endpoint below, a reference is required, as is a payment date and an associated Paygate Bureau Group to submit with.

HTTP POST
/bureau-submissions/

Example Request:

{
  "submissionReference": "MONTHLYSUB01",
  "contraNarrative": "CONTRA",
  "paymentDate": "2024/08/20",
  "groupId": "e45a26c0-9c46-457f-961d-9eafc249e380"
}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process. If successful, a SubmissionID and URL are returned to be used at other points in this process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Delete Submission

Submissions can be deleted by querying the endpoint below.

HTTP DELETE
/bureau-submissions/?submissionId={SUBMISSION-ID}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Update Submission

The Submission can be updated by performing a PUT request to the URL below:

HTTP PUT
/bureau-submissions/

Example Request:

{
  "submissionReference": "MONTHLYSUB01",
  "contraNarrative": "CONTRA",
  "paymentDate": "2024/08/20",
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1"
}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process. If successful, a SubmissionID and URL are returned to be used at other points in this process.

Example Resposne:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Get Submission

Details of a submission can be returned by querying the URL below.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}

The response object from the Get request contains a lot of useful information around the submission, such as debit and credit totals, the number of Direct Debit Instructions and summaries of the blocks contained in the submission. If validated, warning/fix/information/duplicate counts for transaction records within are also displayed.

Example Response:

{
  "submissionId": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionReference": "MONTHLYSUB123",
  "job": "Monthly Job",
  "group": "My Submission Group",
  "created": "2019-08-24T14:15:22Z",
  "lastModification": "2019-08-24T14:15:22Z",
  "createdBy": "Malcom Tucker",
  "status": "Open",
  "locked": false,
  "editingUser": "Terri Coverley",
  "creditCount": 500,
  "creditAmount": 500,
  "debitCount": 500,
  "debitAmount": 500,
  "ddiCount": 100,
  "totalCount": 1100,
  "totalAmount": 1000,
  "infoCount": 10,
  "fixCount": 0,
  "warningCount": 0,
  "duplicateCount": 0,
  "processingDate": "2019-08-24T14:15:22Z",
  "paymentDate": "2019-08-24T14:15:22Z",
  "blockCount": 1,
  "blocks": [
    {
      "submissionId": "643064ba-6a30-433e-ac9d-08d3dd121862",
      "blockNumber": 1,
      "serviceUserNumber": 1234567,
      "processingDate": "2024/10/12",
      "paymentDate": "2024/10/13",
      "creditCount": 500,
      "creditAmount": 500,
      "debitCount": 500,
      "debitAmount": 500,
      "ddiCount": 100,
      "totalCount": 1100,
      "totalAmount": 1000,
      "infoCount": 42,
      "fixCount": 1,
      "warningCount": 3,
      "duplicateCount": 2,
      "originatorAccountName": "John Smiths Business",
      "originatorSortCode": 123456,
      "originatorAccountNumber": 342391,
      "customerReference": "SMITH123",
      "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "customerUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "blockUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1/records"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks"
}

Get records for submission that have validation messages

Using the URL below it is possible to query the submission for a collection of all Transaction Records that have validation messages associated with them.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/validation-messages

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get records for submission that have warnings

Using the URL below it is possible to query the submission for a collection of all Transaction Records that have validation warnings associated with them.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/warnings

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get records for submission that have information messages

Using the URL below it is possible to query the submission for a collection of all Transaction Records that have validation information messages associated with them.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/info

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get records for submission that are duplicates

Using the URL below it is possible to query the submission for a collection of all Transaction Records that have validation messages indicating that the record is a duplicate associated with them.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/duplicates

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get records for submission that require a fix

Using the URL below it is possible to query the submission for a collection of all Transaction Records that have validation messages requiring a fix associated with them.

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/fix

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Submission Blocks

Using the URL below, the blocks associated with a Submission can be returned using a HTTP GET request:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks

The response contains the URL for the block, and the records within, as well as information summarising the contents of the Submission Block.

Example Response:

{
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockCount": 1,
  "blocks": [
    {
      "submissionId": "643064ba-6a30-433e-ac9d-08d3dd121862",
      "blockNumber": 1,
      "serviceUserNumber": 1234567,
      "processingDate": "2024/10/12",
      "paymentDate": "2024/10/13",
      "creditCount": 500,
      "creditAmount": 500,
      "debitCount": 500,
      "debitAmount": 500,
      "ddiCount": 100,
      "totalCount": 1100,
      "totalAmount": 1000,
      "infoCount": 42,
      "fixCount": 1,
      "warningCount": 3,
      "duplicateCount": 2,
      "originatorAccountName": "John Smiths Business",
      "originatorSortCode": 123456,
      "originatorAccountNumber": 342391,
      "customerReference": "SMITH123",
      "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "customerUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "blockUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1/records"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks"
}

Add Block to Submission

Additional blocks can be added to the Submission by performing a POST operation to the URL below. Although not required, it is possible to prepopulate the added block with Transaction Records by including them in the request body.

HTTP POST
/bureau-submissions/add-block

Example Request:

{
  "contraNarrative": "CONTRA",
  "paymentDate": "2024/10/23",
  "customerReference": "YOURCUST001",
  "records": [
    {
      "amount": 10.51,
      "processingDate": "2024/08/22",
      "accountName": "Mr Ollie Reeder",
      "accountNumber": "01234567",
      "sortCode": "012345",
      "transactionCode": "17",
      "userReference": "P4YM3NT123"
    }
  ],
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1"
}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process. If successful, a SubmissionID and URL are returned to be used at other points in this process. A Block Number and URL are also returned.

Example 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"
}

Update a block

Updating a block is performed by performing a PUT request to the endpoint below:

HTTP PUT
/bureau-submissions/update-block

Example Request:

{
  "contraNarrative": "CONTRA",
  "paymentDate": "2024/10/23",
  "customerReference": "YOURCUST001",
  "records": [
    {
      "amount": 10.51,
      "processingDate": "2024/08/22",
      "accountName": "Mr Ollie Reeder",
      "accountNumber": "01234567",
      "sortCode": "012345",
      "transactionCode": "17",
      "userReference": "P4YM3NT123"
    }
  ],
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "blockNumber": 1
}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Get Submission Block

Individual Submission Blocks can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}

Example Response:

{
  "submissionId": "643064ba-6a30-433e-ac9d-08d3dd121862",
  "blockNumber": 1,
  "serviceUserNumber": 1234567,
  "processingDate": "2024/10/12",
  "paymentDate": "2024/10/13",
  "creditCount": 500,
  "creditAmount": 500,
  "debitCount": 500,
  "debitAmount": 500,
  "ddiCount": 100,
  "totalCount": 1100,
  "totalAmount": 1000,
  "infoCount": 42,
  "fixCount": 1,
  "warningCount": 3,
  "duplicateCount": 2,
  "originatorAccountName": "John Smiths Business",
  "originatorSortCode": 123456,
  "originatorAccountNumber": 342391,
  "customerReference": "SMITH123",
  "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
  "customerUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
  "blockUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/643064ba-6a30-433e-ac9d-08d3dd121862/blocks/1/records",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Remove Block from Submission

Blocks can be removed from the submission by performing a HTTP DELETE request to the URL Below:

HTTP DELETE
/bureau-submissions/delete-block?submissionId={SUBMISSION-ID}&blockNumber={BLOCK-NUMBER}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Get Transaction Records for Block

The Transaction Records for a block can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/records

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Transaction Records for Block with validation messages

The Transaction Records for a block that have associated validation messages can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/validation-messages

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Transaction Records for Block with a Fix validation returned

The Transaction Records for a block that require a Fix can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/fixes

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Transaction Records for Block with a Warning validation returned

The Transaction Records for a block that require a have a Warning associated with it can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/warnings

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an warning message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Transaction Records for Block with a Information validation returned

The Transaction Records for a block that require a have an Information Message associated with it can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/information

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an information message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Get Transaction Records for Block with a Duplicates validation returned

The Transaction Records for a block that require a have a Duplicate associated with it can be queried using the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/duplicates

Additional parameters that can be passed on the query string:

• filterText : Text to filter the results by
• perPage : the number of records to display per request
• page : the current page
• orderBy : field to sort by
• orderDirection : direction to sort, either ASC or DESC

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "count": 10,
  "currentPage": 1,
  "totalPages": 10,
  "records": [
    {
      "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "blockNumber": 1,
      "recordNumber": 1,
      "name": "MR. Peter Manion",
      "sortCode": "012345",
      "accountNumber": "01234567",
      "userReference": "JOHNSMITHPAY1",
      "transactionCode": "17",
      "amount": 10.12,
      "messages": [
        "This is an duplicate message generated by Pre Sub Validation"
      ],
      "processingDate": "2024/10/23",
      "paymentDate": "2024/10/24",
      "information": 1,
      "duplicates": 0,
      "warnings": 0,
      "fix": 0,
      "blockUrl": "/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
      "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
      "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
    }
  ],
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "blockLevelValidationMessages": [
    "Example Block Level Validation Message"
  ]
}

Add Records to a block

Records can be added to a block by performing a POST request to the URL below:

HTTP POST
/bureau-submissions/add-records

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "blockNumber": 1,
  "records": [
    {
      "amount": 10.51,
      "paymentDate": "2024/08/22",
      "accountName": "Mr Ollie Reeder",
      "accountNumber": "01234567",
      "sortCode": "012345",
      "transactionCode": "17",
      "userReference": "P4YM3NT123"
    }
  ]
}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Get Transaction Record

Individual Transaction Records can be quried by performing a HTTP GET request to the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/blocks/{BLOCK-NUMBER}/records/{RECORD-NUMBER}

The response will contain any validation messages (if validated), as well as the provided information about the transaction record.

Example Response:

{
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "recordNumber": 1,
  "name": "MR. Peter Manion",
  "sortCode": "012345",
  "accountNumber": "01234567",
  "userReference": "JOHNSMITHPAY1",
  "transactionCode": "17",
  "amount": 10.12,
  "messages": [
    "This is an information message generated by Pre Sub Validation"
  ],
  "processingDate": "2024/10/23",
  "paymentDate": "2024/10/24",
  "information": 1,
  "duplicates": 0,
  "warnings": 0,
  "fix": 0,
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Update Transaction Record

Individual Transaction Records can be updated by performing a HTTP PUT request to the URL below:

HTTP PUT
/bureau-submissions/update-transaction-record

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "recordNumber": 1,
  "blockNumber": 1,
  "amount": 10.5,
  "paymentDate": "2019-08-24T14:15:22Z",  
  "accountName": "Mr. Tom Barnaby",
  "accountNumber": "01234567",
  "sortCode": "123456",
  "transactionCode": "17",
  "userReference": "JOHNSMITHPAY123"
}

The response will contain a boolean value indicatating success, any messages generated by the process and URLs and IDs for the Submission, Block and Record Number.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockNumber": 1,
  "recordNumber": 1,
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "blockUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1",
  "recordsUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records",
  "recordUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f/blocks/1/records/1"
}

Delete Transaction Record

Individual Transaction Records can be deleted by performing a HTTP DELETE request to the URL below:

HTTP DELETE
/bureau-submissions/delete-transaction-record?submissionId={SUBMISSION-ID}&blockNumber={BLOCK-NUMBER}&recordNumber={RECORD-NUMBER}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Reopen Submission

Once a submission has progressed to the Action stage in paygate, it can no longer be edited. Submissions can be reopened for editing as long as they have not been submitted by sending a HTTP POST request to the endpoint below:

HTTP POST
/bureau-submissions/reopen-submission?submissionId={SUBMISSION-ID}

A response is returned with a boolean value indicating success, as well as any relevant messages generated by the process.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Get Bureau Customers for Submission

A collection of the Bureau Customers associated with a submission can be queried by sending a POST request to the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/bureau-customers

Example Response:

{
  "customers": [
    {
      "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"
      },
      "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "reference": "YOURCUST001",
      "customerUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/",
      "notesUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
      "jobsUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
      "submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
    }
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Get SUNS for Submission

A collection of the Service User Numbers (SUNs) associated with a submission can be queried by sending a POST request to the URL below:

HTTP GET
/bureau-submissions/{SUBMISSION-ID}/suns

Example Response:

{
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "suns": [
    "0123456",
    "6543210"
  ]
}

Start Submission

Once a submission has been built and validated, it may be progressed into the BACS submission process by performing a POST request to the endpoint below. A callback URL can be included in the request to notify an external endpoint once complete.

HTTP POST
/bureau-submissions/start

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "callBackUrl": "http://endpoint.yoursite.com/expectedresult"
}

The expected response will contain a boolean value indicating success, any assoicated messages generated by the process and the relevant URLs needed to progress the action.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/bacs/action/?ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Validate Submission

Prior to submission, the submission must be validated to ensure that the data going to BACS will not cause any submission errors. A HTTP POST request to the endpoint below will initiate the validation process, which could be quite long running. Passing in a callbackUrl in the request body will allow external api endpoints to be notified upon completion.

HTTP POST
/bureau-submissions/validate

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "callBackUrl": "http://endpoint.yoursite.com/expectedresult"
}

As well as a boolean value indicating success and messages generated by the process, the expected response from the validate method call will include a URL with which the validation process can be monitored.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac",
  "taskProgressUrl": "/api/v1/bureau-submissions/validation-progress?submissionId=2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac"
}

Validate Submission Block

Individual submission blocks can be validated. A HTTP POST request to the endpoint below will initiate the validation process, which could be quite long running. Passing in a callbackUrl in the request body will allow external api endpoints to be notified upon completion.

HTTP POST
/bureau-submissions/validate-block

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "callBackUrl": "http://endpoint.yoursite.com/expectedresult",
  "blockNumber": 1
}
````

As well as a boolean value indicating success and messages generated by the process, the expected response from the validate method call will include a URL with which the block validation process can be monitored.

Example Response:

```json
{
  "blockNumber": 1,
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac",
  "taskProgressUrl": "/api/v1/bureau-submissions/block-validation-progress?submissionId=2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac&blockNumber=1"
}

Gets the validation progress for a submission

The validation process for a submission can be queried using the endpoint below:

HTTP GET
/bureau-submissions/validation-progress?submissionId={SUBMISSION-ID}

Example Response:

{
  "id": "2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac",
  "progress": 64,
  "message": "locked",
  "userId": "f47d0a8d-a2f0-4c93-a74e-587647e830d1"
}

Gets the validation progress for a block

The validation process for a submission block can be queried using the endpoint below:

HTTP GET
/bureau-submissions/block-validation-progress?submissionId={SUBMISSION-ID}&blockNumber={BLOCK-NUMBER}

Example Response:

{
  "id": "2436ed4d-fdb9-4bcc-a3dd-9f8e1a5aa9ac",
  "fileNumber": 1,
  "progress": 64,
  "message": "locked",
  "userId": "f47d0a8d-a2f0-4c93-a74e-587647e830d1"
}

Gets the validation summary for a submission

A Validation Summary for a submission can be retrieved by performing a HTTP GET request to the endpoint below:

HTTP GET
/bureau-submissions/validation-summary?submissionId={SUBMISSION-ID}

Example Response:

{
  "bureauSubmissionStatus": "Open",
  "error": false,
  "errorMessage": "",  
  "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
}

Unlock submission

If another user is editing the Bureau Submission, it will be unavailable for editing. The unlock submission method will allow the submission to be edited by a new user, who will take ownership at that point.

HTTP POST
/bureau-submissions/unlock-submission

Example Request:

{
  "submissionId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1"
}

Example Response:

{  
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/bacs/action/?ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}