PTX API (1.0)

Download OpenAPI specification:Download

Introduction

This is the documentation for the PTX Payments API.

The PTX Payments 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 testing against our online RESTful API: https://payments.cat.uk.pt-x.com/

◦ If in production with our online RESTful API: https://uk.pt-x.com/

◦ If using your own network, you'll need to use the URL/IP address on which you are hosting the service.

Errors

PTX 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 PTX 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.node01; 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

Example for CAT system

Note: Items in bold are fixed/mandatory.

POST /payments-service/api/security/login HTTP/1.1
Host:payments.cat.uk.pt-x.com
User-Agent:api-v2.5
Cookie:JSESSIONID=Ig3ayRxj1vV17QzUrqPRj-OPgIkQ4Vtihj3lu09TRgt135wAcjQF!-1331583496.node01; 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"
}

Example for live system

Note: Items in bold are fixed/mandatory.

POST /payments-service/api/security/login HTTP/1.1
Host:uk.pt-x.com
User-Agent:api-v2.5
Cookie:f5avraaaaaaaaaaaaaaaa_session_=DFEALBAPPPCOMKFPMHAKMPKHMLOJBNAGGGJLKOHELAEOACOEOOPLCKEMKDFMAPDGIOODBMJACDOGMBHNCCDAFABCOOAIICONKAHEOOIKOMIPOGDDKFHNPLJKOOHONLJN; JSESSIONID=Ig3ayRxj1vV17QzUrqPRj-OPgIkQ4Vtihj3lu09TRgt135wAcjQF!-1331583496.node01; 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"
}

Notes

  • 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, along with the JSESSIONID returned from the handshake are 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.node01; 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: payments.cat.uk.pt-x.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 Profiles

Payment profiles are used for making payments.

Payment Profiles contain all the information that the PTX 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 PTX.

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": [
    ]
}

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 PTX 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://uk.pt-x.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://uk.pt-x.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://uk.pt-x.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://uk.pt-x.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://uk.pt-x.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://uk.pt-x.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. You can run queries to list instructions using reference, creation date and batch ID.

Note: You can add as many instructions to a payment batch (max 1.2 million) before closing (approving/committing) the batch. For example, create a new batch, add 600 instructions, and then close the batch. This will maximise efficiency and minimise costs.

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"

Possible values:

Value Description transactionTypeCode
0 Direct Credit 99
1 DD Regular Collection 17
2 DD First Collection 01
2 DD First Collection 01
3 DD Re-presented 18
4 DD Final Collection 19
5 Dividend Payments Z5
6 Interest Payments Z4
7 DDI New Instruction 0N
8 DDI Cancel Instruction 0C
9 DDI Convert Instruction 0S
10 Standing orders 99
11 Automated Settlement 86
12 Automated return of unapplied credits RA
13 Automated return of unpaid Direct Debit – first collection U1
14 Automated return of unpaid Direct Debit – regular collection U7
15 Automated return of unpaid Direct Debit – re-presented U8
16 Automated return of unpaid Direct Debit – final collection U9
17 Automated teller collection 07
18 Claims for unpaid cheques 13
19 Automated recalls of standing orders and Direct Credits 99
20 Credit card debit E1
21 Credit card refund E2
text
required
string <string>
Default: "STC TEXT"

Text that appears on the statement.

paymentDate
required
string <date-time>

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.

Note: This field is optional for direct credits and mandatory for direct debits.

name
string <string>

The destination account name.

Note: This field is optional for direct credits and mandatory for direct debits.

batchId
required
integer <int64>
Default: 101036

Unique identifier of batch for update.

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": "2022-10-24T00:00:00.000",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "reference": "Reference-101",
  • "name": "JON SMITH",
  • "batchId": 101,
  • "amount": "402.35"
}

Response samples

Content type
application/json
{
  • "@type": "MdeEntry",
  • "id": 1056,
  • "batchId": 101,
  • "index": 42,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "reference": "Reference-101",
  • "name": "JON SMITH",
  • "text": "STC TEXT",
  • "type": "DBACS",
  • "transactionType": "0",
  • "transactionTypeCode": "99",
  • "paymentDate": "2022-10-24T00:00:00.000",
  • "amount": "402.35",
  • "status": "DF",
  • "included": true,
  • "isDDMEntry": false,
  • "createdDate": "2022-10-18T00: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://uk.pt-x.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.

@type
string <string>
Default: "MdeEntry"

The type of record.

id
int <int64>

Unique identifier of batch file.

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.

reference
string <string>

The payment reference.

name
string <string>

The destination account name.

text
required
string <string>

Text that appears on the statement.

type
string <string>
Default: "DBACS"

The type of instruction.

transactionType
required
string <string>

Possible values:

Value Description transactionTypeCode
0 Direct Credit 99
1 DD Regular Collection 17
2 DD First Collection 01
2 DD First Collection 01
3 DD Re-presented 18
4 DD Final Collection 19
5 Dividend Payments Z5
6 Interest Payments Z4
7 DDI New Instruction 0N
8 DDI Cancel Instruction 0C
9 DDI Convert Instruction 0S
10 Standing orders 99
11 Automated Settlement 86
12 Automated return of unapplied credits RA
13 Automated return of unpaid Direct Debit – first collection U1
14 Automated return of unpaid Direct Debit – regular collection U7
15 Automated return of unpaid Direct Debit – re-presented U8
16 Automated return of unpaid Direct Debit – final collection U9
17 Automated teller collection 07
18 Claims for unpaid cheques 13
19 Automated recalls of standing orders and Direct Credits 99
20 Credit card debit E1
21 Credit card refund E2
transactionTypeCode
string <string>

Transaction code of the instruction.

paymentDate
required
string <date-time>

The payment date of the instruction.

amount
required
string <amounts>

The payment amount.

status
required
string <string>

The status of the instruction.

included
boolean

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

isDDMEntry
boolean
Default: false

Alternative identifier for DDM instructions.

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
{
  • "@type": "MdeEntry",
  • "id": 100,
  • "batchId": 101,
  • "index": 1,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "reference": "Reference-1234",
  • "name": "JON SMITH",
  • "text": "STC TEXT",
  • "type": "DBACS",
  • "transactionType": "0",
  • "transactionTypeCode": "99",
  • "paymentDate": "2022-06-19T00:00:00.000",
  • "amount": "402.35",
  • "status": "DF",
  • "included": true,
  • "isDDMEntry": false,
  • "createdDate": "2022-06-05T00:00:00.000",
  • "paymentType": "Bacs",
  • "isRefund": false
}

Response samples

Content type
application/json
{
  • "@type": "MdeEntry",
  • "id": 1056,
  • "batchId": 101,
  • "index": 42,
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "reference": "Reference-10",
  • "name": "JON SMITH",
  • "text": "STC TEXT",
  • "type": "DBACS",
  • "transactionType": "0",
  • "transactionTypeCode": "99",
  • "paymentDate": "2022-06-19T00:00:00.000",
  • "amount": "402.35",
  • "status": "DF",
  • "included": true,
  • "isDDMEntry": false,
  • "createdDate": "2022-06-05T00:00:00.000"
}

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://uk.pt-x.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://uk.pt-x.com/payments-service/api/bacs/instructions/101/included/true

Query all instructions by batch ID

Executes a query to search for instructions 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 all instructions by creation date

Executes a query to search for instructions greater than or equal to a specified created date.

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 all instructions by creation date and batch ID

Executes a query to list instructions by creation date and 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 all instructions by reference and batch ID

Executes a query to list instructions by reference and 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": [
    ]
}

File Upload

Payment instructions are used for making payments and can be added to PTX 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://uk.pt-x.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 PTX, obtained from the Upload a file call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.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": [
    ]
}

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://uk.pt-x.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>

Bacs Messages

Bacs Messages are reports sent from Bacs to PTX 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://uk.pt-x.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://uk.pt-x.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 and readStatus are mandatory for the request.

path Parameters
serviceType
required
string <string>

Unique identifier of the service type. Either set to BACSTel-IP or SECURE-IP.

reportId
required
integer <int64>

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

readStatus
required
integer <int64>

Indicates if PTX should mark the message as read after the download.

Responses

Request samples

curl -H "Content-Type: application/json" -X PUT 
https://uk.pt-x.com/payments-service/api/bacs-messages/BACSTel-IP/bacs-report/9774/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://uk.pt-x.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 PTX reaction is not needed.
  • REVIEW - at least one item required by PTX was not actioned in DDM and needs checking.
  • APPLIED - received and PTX 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": [
    ]
}

Collection Profiles

Collection Profiles are used for Direct Debit collections.

Collection profiles contain all the information that the Direct Debit Management system needs for processing direct debit payments including email preferences, document settings and notice period for mandates.

Query list all collection profiles

Executes a query to list all collection 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": [