API docs by Redocly

API (1.0)

Download OpenAPI specification:Download

Introduction

The API is organized around REST and is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

We use built-in HTTP features, like HTTP authentication and HTTP verbs (methods), which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API.

The URL you will target depends on how you're using the service. If using your own network, you'll need to use the URL/IP address on which you are hosting the service. Refer to product specific documentation for more details.

Errors

The server uses conventional HTTP response codes to indicate the success or failure of an API request. Any unsuccessful response codes will contain more information to help you to identify the cause of the problem.
In general:

  • 2xx status codes indicate that the client's request was successfully received, understood and accepted.
  • 4xx status codes indicate that an error caused by the client has occurred, for example a required parameter was missing, a charge failed, etc.
  • 5xx status codes indicate that an error with the servers has occurred.

Authentication

Authenticate your account by performing a handshake to obtain a CSRF token and JSESSIONID, these are used in the login request. All API calls should then contain the header information obtained from the handshake and authentication and must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The authentication will expire after approximately 10 minutes and the process will then need to be repeated.

Handshake

First perform the handshake with the API to obtain the CSRF token and the JSESSIONID:

GET /payments-service/api/security/handshake

Extract the JSESSIONID cookie from the Set-Cookie field in the response cookie (not the header response), extracting the ID only (highlighted in bold in the example below):

JSESSIONID=yGQz2iZLf8mDb2D7M8nL0f8cxFcjNwBjVimJab8C41kUiNTkVyMA!1781984570; path=/; HttpOnly; Secure;

Then extract the CSRF Token from the X-CSRF field in the response header.

The JSESSIONID and CSRF are then used in the login request header below.

Authenticate

Using the JSESSIONID cookie, and X-CSRF header token from the handshake call, make a POST call to this URL:

/payments-service/api/security/login HTTP/1.1

Ensure to include the following additional, mandatory headers:

User-Agent:api-v2.5
Content-Type:application/json

Here is an example below. (Note: Items in bold are fixed/mandatory):

POST /payments-service/api/security/login HTTP/1.1
Host:example.com
User-Agent:api-v2.5
Cookie:JSESSIONID=Ig3ayRxj1vV17QzUrqPRj-OPgIkQ4Vtihj3lu09TRgt135wAcjQF!-1331583496; TS010ce9a5=0188c34b1367edbe78653c5225eb697178166c6eab65b122b65781e659677d74265561228edc25616390080c41a285aa5e245eb45a
X-CSRF:Ys9duXU4p4aixevzWzG/qK6MNLitom5cYkceMplsFr4=
Content-Type:application/json
Cache-Control:no-cache
Accept-Encoding:gzip, deflate, br
Connection:keep-alive
Content-Length:450
{
"loginTokens": [{
"key": "com.bottomline.security.provider.login.email",
"value": "Include email address here"
}, {
"key": "com.bottomline.security.provider.login.password",
"value": "Include password here"
}],
"apiVersion": "{\"major\": \"1\",\"minor\": \"0\",\"patch\": \"0\",\"build\": \"0\"}",
"purpose": "cpay-auth",
"tokenLocation": "HEADER"
}

Here is an example below for the Live system. (Note: Items in bold are fixed/mandatory):

POST /payments-service/api/security/login HTTP/1.1
Host:example.com
User-Agent:api-v2.5
Cookie:f5avraaaaaaaaaaaaaaaa_session_=DFEALBAPPPCOMKFPMHAKMPKHMLOJBNAGGGJLKOHELAEOACOEOOPLCKEMKDFMAPDGIOODBMJACDOGMBHNCCDAFABCOOAIICONKAHEOOIKOMIPOGDDKFHNPLJKOOHONLJN; JSESSIONID=Ig3ayRxj1vV17QzUrqPRj-OPgIkQ4Vtihj3lu09TRgt135wAcjQF!-1331583496; TS010ce9a5=0188c34b1367edbe78653c5225eb697178166c6eab65b122b65781e659677d74265561228edc25616390080c41a285aa5e245eb45a X-CSRF:Ys9duXU4p4aixevzWzG/qK6MNLitom5cYkceMplsFr4=
Content-Type:application/json
Cache-Control:no-cache
Accept-Encoding:gzip, deflate, br
Connection:keep-alive
Content-Length:450
{
"loginTokens": [{
"key": "com.bottomline.security.provider.login.email",
"value": "Include email address here"
}, {
"key": "com.bottomline.security.provider.login.password",
"value": "Include password here"
}],
"apiVersion": "{\"major\": \"1\",\"minor\": \"0\",\"patch\": \"0\",\"build\": \"0\"}",
"purpose": "cpay-auth",
"tokenLocation": "HEADER"
}

Please note: - Some languages may add HTTP/1.1 by default so may not need to be manually added. - The JSESSIONID cookie may be added automatically by some API programs but must start with JSESSIONID= - Use the JSESSIONID from the response cookies, as the same cookie may not always be presented in the response headers. - Ensure all mandatory fields and values (shown in bold in examples) are added exactly the same, including positioning. - Some API programs will normally include the TS and F5 cookies with the final payload being sent, so may not be necessary to add in addition. - The apiVerson in some languages may need additional slashes included to ensure the values are added exactly.

The X-CSRF token and auth.token returned in the Authenticate response are then required in all future API calls.

Once the authentication is successful, it will expire in approximately 10 minutes if not used (the timer is reset with successful API request). API integrations will need to correctly handle HTTP401 responses and repeat the above handshake and authenticate steps.

Using the API

API calls should contain the header information collected from the handshake and login.

Note: Ensure that the CSRF token that is used is the value returned by the login call and not the handshake call which will be out of date.

Example call

The API call below is an example for creating a new payment batch and most calls will follow this format. However, always refer to the specific documentation for each API call regarding header, request and response information.

POST /payments-service/api/bacs/batches HTTP/1.1
User-Agent:api-v2.5
Cookie:JSESSIONID=Y1cXNhhhCapIMdC3EKnsKP0djemJoq7DorVHf6zNzyHnLxTVmId5!-1275828986; TS010ce9a5=0188c34b1367edbe78653c5225eb697178166c6eab65b122b65781e659677d74265561228edc25616390080c41a285aa5e245eb45a X-CSRF:WQgmaV4zskFD0DzPdiii5ESbwx+G9EJlZ7mTL2Zz7Kc=
Content-Type:application/json
com.bottomline.auth.token:AAABcRcyoUYTHdHNVjB2d496zvTNGVzOgPu+sNhY4xZSVYtHIDx4weJY6WpcQMZcI627EOgYnbEAM3W57zM7p9HGN712Tz+YEIHM4UG6mtUVKNpKxk6qkrIc4KaFp/ue+/qCHf+FDIyMAd7F8YvwTpVL1t8/N+bUnyO+qqOk/e4EcDHOrvbyHL0cDRMBcZ4V+vToZQRA333sPc8RdqbT3Xs08qOvlXZyns9ux1/haGAyMuyYuFGBAU2GDernzcosSAlCTr0HAII24XTJKSK1uRdO59fbbe6rwIGCXASemMoXpMFaY8xx22oxMKrc5HAolcmYNGSlmEXJ/CiXJkDtnJxu4nryEHgJAvd/uU6TGOS+BfWwELXsZOkpGzshDe6O+FCptIsMTYNPBTCebHgQmBeCUGDKCRMHTJYCpPRPHgwZGm7f5Oe+VCII9Mqeb+m90s+aNDY9x9cYirAhoGEs1gHvt+K92vftulgeOWdYLR2hnmxK9wYa/hJg38f3w9fap00VEcjzEsGBuO1qql5OuWwVcomcdXpW41ioM83eZFfDlMKMDUCc/2OK8vFXlhEttk3ygg8q3M2myo0DlmmypptbpNZrcZGTqnirrgKGuqOJo7LSFaMjbSvVAzOcCwNUKPuuuQGEke/QRJkLfK8yEZ6RD9VW5gnB6oBmtAiVyMyKgnVS8CYTNbCnIHwZyr25zY2W4A5hHa8I03TclglRc1wi1bKe6pndiLVX1UKbzeAR0Xgqq7pNWTLotxtBmj2e/VB7Eb60yjNbjao1y5YoyzzFcQP9sPFNQ1kWWxBSkEawIbGMT+tD3NR6wqAjK5j2Bjfuu4r9PhOC/0R/FSkLhpxnxsUR36bb1FteWe4YcC2nFfFcxgmCBjyQ/tE/6uLfQWAWH8aBUw+FWpZH18tZJYxzKMPjJkMZ1+m28p+htQM8zqne6uT7U6jxWHcUxR8tLQN7KK8myCg7BA0k4tTJZu4v6jz6U/LyIvnnKYRupFp9sQVKXuh77npGLExhLoir2BeegkhYpv60zDEuOELuZyb/d3TyBRLrjUkBLCjM/AkKoAd1IlvD1AABoMPjLLRlAVJwCc2Vd7Lj7Hw6GfPsm1Bc4Pbfb8TwIfMirfBt4SpCQIVmGzGDzkz98h15wlptThST43t/ZNgx33LdnhOBNyTJQWgc11F/1SlO1zLVg8FqCPS4LgutZSSBMX6HZkUezGT8LETAaxq1WrYh2JyeWrmyBvydoVqmqoo5MJ+PSJXIuUXTqkcx39HygqZLHmXQBcxg9vuTcfVdvLaI1wrPnh2uUP98L6JCltGBeFHhMF5fp/ekqRyII8SqpCua6Se99JMk3KpQcsi8sVZ5STnS47wN8WhcdBWgf1h1CTn/My3/Cs8XHKJCUVseS8jkaKYYMGpF0DLeEXhWUuq58qxIugtaAjQUxr0iHEwcjVZEC88f523ngfGwbwWBt58ECmLuR+jIXhwOTuAj3HjR2vlYjEXcllRyRNn3xcjIjUlLajsv9EjcSzbbpWWykQ6xiaVwCpJyXGwg72gnQZNjV+dvBRG1Qh7C3VWYTzXjSsLynsxDt0ziT4ZWyO9xnSeamgBZPPPsux6BPjekvnI8ppQCjrt5Qm9sJSxoyaTKyPx0lq1/nzMYyx+spIdmBiwkUPsw/Dnli7gAOnSgH3B/xl6l1Ss4Y5RDhG0ElQ==
Accept:/
Cache-Control:no-cache
Host: example.com Accept-Encoding:gzip, deflate, br Connection:keep-alive Content-Length:199 { "inputMethod":"manual",
"description":"BATCH 2",
"application":"1234",
"applicationName":"-",
"status":"-",
"paymentDate":"-",
"submissionSigningMethod":"SMARTCARD" }

Data Types

String

For all API calls, parameters of type string cannot start with any of the following charaters: =, +, -, @

Payment Batches

Payment batches are used for making payments. A payment batch contains payment instructions details.

The API allows you to create a batch which will upload the payment into the system. You can create a batch template and create a batch from the template. You can also move a batch from draft to entered, approved or committed status.

Create a new payment batch

Creates a new payment batch.

Note: Create an empty batch first and then use the Create an instruction call to add instructions to the batch.

Request Body schema: application/json
required

The MdeHeader

inputMethod
string <string>

Input method, set to either Manual or File.

description
string <string>

Description for batch.

application
required
string <string>

Unique identifier of the selected payment profile.

applicationName
string <string>

The name of the selected payment profile.

status
string <string>
Default: "DRAFT"

The status of the batch.

paymentDate
string <date-time>

The payment date of the batch. If supplied then must adhere to Bacs scheme rules (the earliest date is two days from the current date excluding bank holidays and weekends).

paymentType
string <string>

The payment type, set to either Bacs or Faster Payments.

submissionSigningMethod
string
Default: "SMARTCARD"

The signing method when submitting files to Bacs, set to either Smartcard or HSM.

Responses

Request samples

Content type
application/json
{
  • "inputMethod": "manual",
  • "description": "New batch",
  • "application": 6421,
  • "applicationName": "TEST PAYMENT PROFILE",
  • "status": "-",
  • "paymentDate": "-",
  • "paymentType": "Bacs",
  • "submissionSigningMethod": "SMARTCARD"
}

Response samples

Content type
application/json
{
  • "@type": "MdeHeader",
  • "id": 100,
  • "application": 33,
  • "applicationName": "Direct MDE Profile",
  • "enteredDate": "2018-10-18T13:13:24.000+0000",
  • "paymentDate": "2018-10-22T00:00:00.000",
  • "enteredBy": "JGX3FTUOQF1PPIDQTMLF",
  • "description": "TEST PAYMENT PROFILE-1539868404142",
  • "status": "DRAFT",
  • "statusDescription": "Draft",
  • "debitCount": 3,
  • "debitTotal": 623.45,
  • "creditCount": 0,
  • "creditTotal": 0,
  • "paymentType": "Bacs",
  • "originatorInfo": {
    },
  • "errorCount": 0,
  • "warningCount": 0,
  • "auddisCount": 0,
  • "submission": 126091,
  • "multiplePaymentDates": false,
  • "entryCount": 0,
  • "includedCount": 0,
  • "rti": false,
  • "possibleDuplicate": false,
  • "indirect": false,
  • "paymentFileSigned": false,
  • "riskCount": 0,
  • "isDDMEntry": false
}

Create a new payment batch template

Creates a new payment batch template.

path Parameters
batchId
required
integer <int64>

Unique identifier of batch for template creation.

Request Body schema: application/json

The Bacs template descriptor.

templateName
string <string>

Template name.

batchId
integer <int64>

The batch ID for template creation.

Responses

Request samples

Content type
application/json
{
  • "templateName": "MyWeeklyBatchFile",
  • "batchId": 100
}

Response samples

Content type
application/json
{
  • "model": { },
  • "informationMessages": [
    ],
  • "warningMessages": [
    ],
  • "errorMessages": [
    ],
  • "debugMessages": [
    ]
}

Create a new payment batch from template

Creates a new payment batch from a template.

path Parameters
templateId
required
integer <int64>

Unique identifier of template for batch creation.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/batches/124/template/batch

Response samples

Content type
application/json
{
  • "id": 100,
  • "submissionId": 99,
  • "application": 33,
  • "applicationName": "Direct MDE Profile",
  • "entries": [
    ],
  • "applicationDescription": "Direct MDE Profile {100124}",
  • "paymentDate": "2019-08-24T14:15:22Z",
  • "type": "DBACS",
  • "description": "DirectMDEProfile-1515062817535",
  • "debitCount": 3,
  • "debitTotal": 623.45,
  • "creditCount": 14,
  • "creditTotal": 125650.9
}

Complete batch

Completes a payment batch moving the batch from draft to entered status.

Warning: This call is not thread safe therefore DO NOT use this call while instructions are being added to the batch manually or via the API.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

paymentProfileId
required
integer <int64>

Payment profile identifier obtained from the Query list all payment profiles or Query payment profile by payment profile name call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/submissions/126091/enter/6421

Approve batch

Completes a payment batch moving the batch from entered to approved status.

Warning: This call can only be used for batches that are in the entered state.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/submissions/126091/approve

Reject batch

Rejects a payment batch.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

Request Body schema: application/json
reason
string <string>

Reject reason.

Responses

Request samples

Content type
application/json
{
  • "reason": "Duplicate payment"
}

Unapprove batch

Unapproves a payment batch, moving the status of the batch back to Entered.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/submissions/126091/unapprove

Commit batch

Completes a payment batch moving the batch from approved to committed status.

Warning: This call can only be used for batches that have been created using a payment profile for indirect submitters and are in the approved state.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/submissions/126091/commit

Archive batch

Archives a payment batch.

path Parameters
submissionId
required
integer <int64>

Submission identifier obtained from the Create a new payment batch call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/submissions/126091/archive

Query batch by rejected status between two dates

Executes a query for a rejected payment batch between two dates.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Payment Instructions

Payment instructions are used for making payments.

A payment instruction contains the payment details including sort code, account number, payment type and amount. The API allows you to create, delete and update your payment instructions. You can clear the amount in an instruction and identify which instructions to include in a batch.

Create an instruction

Creates a new instruction.

Request Body schema: application/json
required

The MdeEntry

paymentType
string <string>

Payment type of the instruction.

included
boolean

Identifier of the instruction state, if it is included in the batch file or not.

transactionType
required
string <string>
Default: "0"

Transaction type of the instruction, example "0".

Possible values are:

  • 0 (Direct Credit)
  • 1 (DD Regular Collection)
  • 2 (DD First Collection)
  • 3 (DD Re-presented)
  • 4 (DD Final Collection)
  • 5 (Dividend Payments)
  • 6 (Interest Payments)
  • 7 (DDI New Instruction)
  • 8 (DDI Cancel Instruction)
  • 9 (DDI Convert Instruction)
  • 10 (Standing orders)
  • 11 (Automated Settlement)
  • 12 (Automated return of unapplied credits)
  • 13 (Automated return of unpaid Direct Debit – first collection)
  • 14 (Automated return of unpaid Direct Debit – regular collection)
  • 15 (Automated return of unpaid Direct Debit – re-presented)
  • 16 (Automated return of unpaid Direct Debit – final collection)
  • 17 (Automated teller collection)
  • 18 (Claims for unpaid cheques)
  • 19 (Automated recalls of standing orders and Direct Credits)
  • 20 (Credit card debit)
  • 21 (Credit card refund)

text
required
string <string>
Default: "STC TEXT"

Text that appears on the statement.

paymentDate
required
string <date-time>
Default: "2021-06-15T00:00:00.000"

The payment date of the instruction.

sortCode
required
string <string>
Default: "111111"

The destination sort code.

accountNumber
required
string <string>
Default: "11111111"

The destination account number.

reference
string <string>

The payment reference.

name
string <string>

The destination account name.

batchId
required
integer <int64>
Default: 101036

Unique identifier of batch for update.

@type
string <string>
Default: "MdeEntry"

The type of record.

isDDMEntry
boolean
Default: false

Alternative identifier for DDM instructions.

amount
required
string <amounts>
Default: "1222211"

The payment amount.

Responses

Request samples

Content type
application/json
{
  • "paymentType": "Bacs",
  • "included": true,
  • "transactionType": "0",
  • "text": "STC TEXT",
  • "paymentDate": "2021-06-14T00:00:00.000",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "reference": "Reference-101",
  • "name": "JON SMITH",
  • "batchId": 101,
  • "@type": "MdeEntry",
  • "isDDMEntry": false,
  • "amount": "402.35"
}

Response samples

Content type
application/json
{
  • "@type": "MdeEntry",
  • "id": 1056,
  • "batchId": 101,
  • "index": 42,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "text": "STC TEXT",
  • "type": "DBACS",
  • "transactionType": "0",
  • "transactionTypeCode": "99",
  • "paymentDate": "2021-06-14T00:00:00.000",
  • "amount": "402.35",
  • "status": "DF",
  • "included": true,
  • "isDDMEntry": false,
  • "createdDate": "2021-06-15T00:00:00.000",
  • "warning": {
    }
}

Delete an instruction

Deletes an instruction.

path Parameters
entryId
required
integer <int64>

Unique identifier of entry for the deletion.

Responses

Request samples 

curl -H "Content-Type: application/json" -X DELETE 
https://example.com/payments-service/api/bacs/instructions/10045

Edit an instruction

Updates an instruction.

path Parameters
entryId
required
integer <int64>

Unique identifier of entry for the update.

Request Body schema: application/json
required

Unique identifier of entry for the update.

batchId
required
integer <int64>

Unique identifier of batch for update.

index
required
integer <int64>

The index identifier of the instruction within the batch file.

sortCode
required
string <string>

The destination sort code.

accountNumber
required
string <string>

The destination account number.

text
required
string <string>

Text that appears on the statement.

transactionType
required
string <string>

Transaction type of the instruction, example "0".

Possible values are:

  • 0 (Direct Credit)
  • 1 (DD Regular Collection)
  • 2 (DD First Collection)
  • 3 (DD Re-presented)
  • 4 (DD Final Collection)
  • 5 (Dividend Payments)
  • 6 (Interest Payments)
  • 7 (DDI New Instruction)
  • 8 (DDI Cancel Instruction)
  • 9 (DDI Convert Instruction)
  • 10 (Standing orders)
  • 11 (Automated Settlement)
  • 12 (Automated return of unapplied credits)
  • 13 (Automated return of unpaid Direct Debit – first collection)
  • 14 (Automated return of unpaid Direct Debit – regular collection)
  • 15 (Automated return of unpaid Direct Debit – re-presented)
  • 16 (Automated return of unpaid Direct Debit – final collection)
  • 17 (Automated teller collection)
  • 18 (Claims for unpaid cheques)
  • 19 (Automated recalls of standing orders and Direct Credits)
  • 20 (Credit card debit)
  • 21 (Credit card refund)

amount
required
string <amounts>

The payment amount.

status
required
string <string>

The status of the instruction.

createdDate
required
string <date-time>

The date the instruction was created.

paymentType
required
string <string>

Payment type of the instruction.

isRefund
required
boolean

Defines if the payment is a refund. Always set to false.

Responses

Request samples

Content type
application/json
{
  • "batchId": 101,
  • "index": 1,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "text": "STC TEXT",
  • "transactionType": "0",
  • "amount": "402.35",
  • "status": "DF",
  • "createdDate": "2021-06-09T15:21:53.124",
  • "paymentType": "Bacs",
  • "isRefund": false
}

Response samples

Content type
application/json
{
  • "@type": "MdeEntry",
  • "id": 1056,
  • "batchId": 101,
  • "index": 42,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "text": "STC TEXT",
  • "type": "DBACS",
  • "transactionType": "0",
  • "transactionTypeCode": "99",
  • "amount": "402.35",
  • "status": "DF",
  • "included": true,
  • "isDDMEntry": false,
  • "createdDate": "2021-06-15T00:00:00.000",
  • "warning": [
    ]
}

Clear amounts

Clears the amount in an instruction.

path Parameters
batchId
required
integer <int64>

Unique identifier of batch for update.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/instructions/101/amount/clear

Include instructions

Identifies which instructions to include in a batch.

path Parameters
batchId
required
integer <int64>

Unique identifier of batch for update.

included
required
boolean

Has the value true if the instructions should be included.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/bacs/instructions/101/included/true

Payment Profiles

Payment profiles are used for making payments.

Payment Profiles contain all the information that the system needs to process payments including if the payments is to be made via Bacs or Faster Payments, if the payment is to be submitted via a bureau or submitted to Bacs on behalf of a bureau and how the payment data will be uploaded to the system.

Query list all payment profiles

Executes a query to list all payment profiles.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query payment profile by payment profile name

Executes a query to search for a payment profile by name.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

File Upload

Payment instructions are used for making payments and can be added to the system by uploading a file.

The API allows you to upload a Bacs file and retrieve the result of the upload.

Upload a file

Uploads a Bacs payment file.

path Parameters
id
required
integer <int64>

Payment profile identifier

Request Body schema: multipart/form-data
required
file
required
string <binary>

File to upload

Responses

Request samples 

curl -F 'file=@PAYER_FILE' https://example.com/payments-service/api/file/6421

Response samples

Content type
application/json
{}

Retrieve upload result

Retrieves the result of uploading a Bacs payment file.

path Parameters
id
required
integer <int64>

File identifier as generated by the system, obtained from the Upload a file call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X GET 
https://example.com/payments-service/api/file/19456

Response samples

Content type
application/json
{
  • "id": 19456,
  • "filename": "Payment file type.csv",
  • "size": 253,
  • "status": "SUCCESS",
  • "submissionId": 88863,
  • "applicationId": 6264,
  • "batchId": 88864
}

Query success result by batch id

Executes a query for successful Bacs file upload by batch id.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query failed result by batch id

Executes a query for failed Bacs file upload by batch id.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query failed result by submission id

Executes a query for failed Bacs file upload by submission id.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query failed result by batch id and error

Executes a query for failed Bacs file upload by batch id and error.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Bacs Messages

Bacs Messages are reports sent from Bacs to the system for Direct Debit collections.

The API allows you to list, view, export, mark as downloaded and update the status of Bacs messages.

List Bacs messages

Returns a list of Bacs messages (which are not downloaded). The information returned can then be used in the Bacs messages calls.

Note: This call is only available for collection profiles set up for file import. Use the Query list all messages call for collection profiles set up for Manual Data Entry and file import.

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST
        {
  "entity":{
    "name": "BacsMessage",
    "symbol": "com.bottomline.cpay.model.bacs.reports.ReportItem",
    "key": "com.bottomline.cpay.model.bacs.reports.ReportItem"
    },
  "resultFields":[
    {
      "name": "BacsMessage",
      "symbol": "com.bottomline.cpay.model.bacs.reports.ReportItem",
      "fieldType": "OBJECT",
      "key": false
    },
    {
      "name": "rowCount",
      "symbol": "com.bottomline.query.count",
      "fieldType": "LONG",
      "key": false
    }
  ],
  "resultsPage":{
    "firstResult": 0,
    "maxResults": 50
  }
}
https://example.com/payments-service/api/bacs-messages/downloadable

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

View Bacs message

Returns a XML representation of the message. The service type, report Id and report format are mandatory for the request.

path Parameters
serviceType
required
string <int64>

Unique identifier of the service type. Set to either BACSTel-IP or SECURE-IP.

reportId
required
integer <int64>

Unique identifier of the Bacs report.

reportFormat
required
string <int64>
Default: 0

Unique identifier of the report type to be downloaded. Set to:

  • 0 - REPORT_FORMAT_XML (text/xml)

Responses

Request samples 

curl -H "Content-Type: text/html" -X GET 
https://example.com/payments-service/api/bacs-messages/BACSTel-IP/9774/0

Update status of Bacs message

Updates the status of the Bacs message. The service type, report Id, document Id and readStatus are mandatory for the request.

path Parameters
serviceType
required
string <int64>

Unique identifier of the service type.

reportId
required
integer <int64>

Unique identifier of the Bacs report, obtained from calling List bacs messages.

documentId
required
integer <int64>

Unique identifier of the Bacs document, obtained from calling List bacs messages.

readStatus
required
integer <int64>

Indicates if the system should mark the message as read after the download (0 - false, 1 - true)

Responses

Request samples 

curl -H "Content-Type: application/json" -X PUT 
https://example.com/payments-service/api/bacs-messages/BACSTel-IP/bacs-report/9774/223879829/set-read-status/1

Response samples

Content type
application/json
null

Mark Bacs message as downloaded

Marks a Bacs message as downloaded, even if the document is not downloaded. The service type, report Id and document Id are mandatory.

path Parameters
serviceType
required
string <int64>

Unique identifier of the service type. Set to either BACSTel-IP or SECURE-IP.

reportId
required
integer <int64>

Unique identifier of the Bacs report.

documentId
required
integer <int64>

Unique identifier of the Bacs document.

Responses

Request samples 

curl -H "Content-Type: */*" -X POST 
https://example.com/payments-service/api/bacs-messages/mark-downloaded/BACSTel-IP/9774/223879829

Query list all messages

Executes a query to list all Bacs messages. This call is available for collection profiles set up for Manual Data Entry and file import.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query not downloaded

Executes a query for Bacs messages not downloaded.

In the reponse the possible values for the processed field are:

  • BLANK - typical for non-DDM reports where the system reaction is not needed.
  • REVIEW - at least one item required by the system was not actioned in DDM and needs checking.
  • APPLIED - received and the system reaction in the normal/expected manner.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

resultFields
required
Array of any

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Query instruction detail by report id

Executes a query for Bacs messages instruction detail by report id.

Request Body schema: application/json
required

The query to be executed.

required
object (QueryEntity)

The entity in the query.

object (QueryCriteria)

The criteria of the query to be performed on the database.

required
Array of objects (QueryField)

The field values to be returned as the query result.

object (QueryResultsPage)

The controller of the page size to be returned within the processed query. It is recommended that no more than 500 results are returned in a search.

Responses

Request samples

Content type
application/json
{
  • "entity": {
    },
  • "criteria": {
    },
  • "resultFields": [
    ],
  • "resultsPage": {
    }
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "rows": [
    ]
}

Submission Reports

Submission summary reports are provided by the Bacs service at the point of submission and are used to feed back information on payments so that they can be followed up accordingly.

Retrieve submission summary

Retrieves a submission summary report. The HTTP 200 response will contain either the report (if the report exists) or the text "Report is unavailable".

path Parameters
submissionId
required
integer <int64>
Example: 126091

Submission identifier obtained from the Create a new payment batch call.

Responses

Request samples 

curl -H "Content-Type: application/json" -X GET 
https://example.com/payments-service/api/bacs/submissions/126091/report

Response samples

Content type
text/html
<html xmlns:sub="http://bacs.co.uk/submissions"><head><meta http-equiv="Content-Type" content="text/html;" charset="utf-8" /><title>Bacs Payment Servivces - Submissions Summary</title></head><body> .... </body></html>

Users

The API allows you to list the current users in the system and their roles.

.

List all users

Returns a list of all current users.

path Parameters
realmid
required
string
Example: TEST

Realm ID (obtained from Bottomline support)

Request Body schema: application/form-data

Search criteria

object (SearchCriteria)

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST 
https://example.com/payments-service/api/principal/user/TEST/search?maint=true

Response samples

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

List all roles

Returns a list of all roles.

Request Body schema: application/form-data

Identifier

realmKey
string

Realm key (obtained from Bottomline support).

Responses

Request samples 

curl -H "Content-Type: application/json" -X POST
{  
   "identifier":{  
      "realmKey":"TEST"
   }
}
https://example.com/payments-service/api/roles/providers/com.bottomline.banking.webseries.roles.provider.webseries/com.bottomline.banking.webseries.roles.provider.WebSeriesRolesProvider/getRolesForRealm

Response samples

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