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.

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

Query collection profile by collection profile name

Executes a query to search for a collection 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": [
    ]
}

Plan Templates

Plan templates are used for Direct Debit collections.

A plan template is a template for recurring payments, when collection patterns are well defined. The API allows you to create, delete and update your plan templates. You can retrieve individual plan templates as well as a list of all your plan templates.

List all plan templates

Returns a list of all plan templates.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/templates

Response samples

Content type
application/json
[
  • {
    }
]

Create a plan template

Creates a new plan template.

Request Body schema: application/json
required

The plan template model.

object (WeeklyPlanTemplate)
object (MonthlyPlanTemplate)
object (MonthlyPickPlanTemplate)
object (YearlyPlanTemplate)

Responses

Request samples

Content type
application/json
{
  • "WeeklyPlanTemplate": {
    },
  • "MonthlyPlanTemplate": {
    },
  • "MonthlyPickPlanTemplate": {
    },
  • "YearlyPlanTemplate": {
    }
}

Response samples

Content type
application/json
{
  • "WeeklyPlanTemplate": {
    },
  • "MonthlyPlanTemplate": {
    },
  • "MonthlyPickPlanTemplate": {
    },
  • "YearlyPlanTemplate": {
    }
}

Retrieve a plan template

Retrieves a plan template by unique identifier

path Parameters
id
required
integer <int64>

ID of plan template, obtained from the List all plan templates call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/templates/45

Response samples

Content type
application/json
{
  • "WeeklyPlanTemplate": {
    },
  • "MonthlyPlanTemplate": {
    },
  • "MonthlyPickPlanTemplate": {
    },
  • "YearlyPlanTemplate": {
    }
}

Update a plan template

Updates an existing plan template.

path Parameters
id
required
string

ID of plan template, obtained from the List all plan templates call.

Request Body schema: application/json
required

The plan template model.

object (WeeklyPlanTemplate)
object (MonthlyPlanTemplate)
object (MonthlyPickPlanTemplate)
object (YearlyPlanTemplate)

Responses

Request samples

Content type
application/json
{
  • "WeeklyPlanTemplate": {
    },
  • "MonthlyPlanTemplate": {
    },
  • "MonthlyPickPlanTemplate": {
    },
  • "YearlyPlanTemplate": {
    }
}

Response samples

Content type
application/json
{
  • "WeeklyPlanTemplate": {
    },
  • "MonthlyPlanTemplate": {
    },
  • "MonthlyPickPlanTemplate": {
    },
  • "YearlyPlanTemplate": {
    }
}

Delete a plan template

Deletes an existing plan template.

path Parameters
id
required
integer <int64>

ID of plan template, obtained from the List all plan templates call.

Responses

Request samples

curl -H "Content-Type: application/json" -X DELETE 
https://uk.pt-x.com/payments-service/api/ddm/templates/45

Contacts

Contacts are used for Direct Debit collections.

A contact holds a person's or company's details whose accounts will be debited.The API allows you to create, delete and update your contacts. You can retrieve individual contacts as well as a list of all your contacts.

List all contacts

Returns a list of all contacts.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts

Response samples

Content type
application/json
[
  • {
    }
]

Create a contact

Creates a new contact.

Request Body schema: application/json
required

Contact model.

title
required
string

Title.

firstName
required
string

First name of the contact.

lastName
required
string

Last name of the contact.

email
required
string

E-mail address of the contact.

isAttachmentUsed
boolean

If true, communications sent as attachments. Otherwise sent as part of the email body.

communicationPref
required
string (CommunicationPref)
Enum: "LOCAL_PRINT" "EMAIL" "SERVICE_PRINT" "POST"

Communications preference.
Note: LOCAL_PRINT and SERVICE_PRINT are not typically used.

required
object (Address)

The address of the contact.

companyName
string

Company Name

reference
string

Reference is an unique identifier that can be associated with the contact object. If not provided, the PTX system will use the contact Id to generate the reference internally. Reference can be, for example, membership ID, CRM ID or some other ID from an external system. This reference is used on imports when updating an existing contact. If the reference is not provided on the import file, the system will assume that a new contact should be created.

phone
string

Phone number of the contact.
Must not start with any of the characters =, +, - or @.

Responses

Request samples

Content type
application/json
{
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Response samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Retrieve a contact

Retrieves details of a contact using unique identifier.

path Parameters
id
required
integer <int64>

Contact identifier, obtained from the List all contacts call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52

Response samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Update a contact

Updates the details of a contact.

path Parameters
id
required
string

Contact identifier, obtained from the List all contacts call.

Request Body schema: application/json

Contact model.

type
string

Contact type - PERSON.

title
string

Title.

firstName
string

First name of the contact.

lastName
string

Last name of the contact.

email
string

E-mail address of the contact.

isAttachmentUsed
boolean

If true, communications sent as attachments. Otherwise sent as part of the email body.

communicationPref
string (CommunicationPref)
Enum: "LOCAL_PRINT" "EMAIL" "SERVICE_PRINT" "POST"

Communications preference.
Note: LOCAL_PRINT and SERVICE_PRINT are not typically used.

object (Address)

The address of the contact.

id
integer <int64>

Unique identifier for the contact generated by PTX and returned in the response. Used to retrieve, update and delete a contact.

companyName
string

Company Name

reference
string

Reference is an unique identifier that can be associated with the contact object. If not provided, the PTX system will use the contact Id to generate the reference internally. Reference can be, for example, membership ID, CRM ID or some other ID from an external system. This reference is used on imports when updating an existing contact. If the reference is not provided on the import file, the system will assume that a new contact should be created.

phone
string

Phone number of the contact.
Must not start with any of the characters =, +, - or @.

Responses

Request samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Response samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Delete a contact

Deletes an existing contact.

path Parameters
id
required
integer <int64>

Contact identifier, obtained from the List all contacts call.

Responses

Request samples

curl -H "Content-Type: application/json" -X DELETE 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52

Look up address

Looks up the supplied address of the payer.

Request Body schema: application/json
required

Address lookup is performed on the partial address supplied.

lines
required
string

Address lines.
Must not start with any of the characters =, +, - or @, minimum length is 3 and maximum length is 360.

town
required
string

Town.

county
required
string

County.

code
required
string

Postcode.

country
required
string

Country.

Responses

Request samples

Content type
application/json
{
  • "lines": "530 HIGH ST",
  • "town": "WESTBURY",
  • "county": "WILTS",
  • "code": "BA133BN",
  • "country": "UK"
}

Response samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Check address look up

Checks if address lookup is available for the current user.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/address-lookup-available

Response samples

Content type
application/json
{
  • "type": "PERSON",
  • "title": "MR",
  • "firstName": "Carlos",
  • "lastName": "Page",
  • "email": "cpage@mb-contact.com",
  • "isAttachmentUsed": true,
  • "communicationPref": "EMAIL",
  • "address": {
    },
  • "id": 101,
  • "companyName": "Mercedes Benz",
  • "reference": "UniqueReference-1234",
  • "phone": "123456789"
}

Query contact by last name

Executes a query to search for a contact by last 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": [
    ]
}

Query contact by contact ref

Executes a query to search for a contact by contact ref.

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

Mandates

Mandates are used for Direct Debit collections.

A Direct Debit Mandate is an authorisation from your customer to collect future payments from them when they are due. Mandates specify the bank details for the account from which the direct debit payments will be taken. The API allows you to create, delete and update your mandates. You can retrieve individual mandates as well as a list of all your mandates.

List all mandates

Returns a list of all mandates.

path Parameters
contactId
required
string

ID of contact, obtained from the List all contacts call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates

Response samples

Content type
application/json
[
  • {
    }
]

Create a mandate

Creates a new mandate.

path Parameters
contactId
required
string

ID of contact.

Request Body schema: application/json
required

The mandate model.

payerId
required
integer <int64>

The ID of the payer (contact that owns this mandate).

profileId
required
integer <int64>

The collection profile ID that this mandate is associated to.

reference
required
string

Reference of the mandate. This is the reference that is used by the paying bank to register the mandate.

sortCode
required
string

The sort code of the bank account to be debited.

accountNumber
required
string

Account number of the bank account to be debited.

altReference
string

Alternative reference.

This reference is only used if you need to associate the mandate with some other system and the original reference cannot be used, as the key from the other system does not comply with Bacs character requirements. For example, the mandate reference is a maximum of 18 characters and the following characters are valid (&-./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ ). If you wish to associate the mandate with another entity from a system that is longer than 18 characters or contains characters not listed above, then alternative reference should be used.

accountName
required
string

Account name of the account to be debited.

status
string

Status of the mandate, where possible values are ACTIVE, SUSPENDED, CANCELLED, DELETED, DRAFT.

comments
string

Free text you wish to record against the mandate.

created
string <date-time>

Date and time when the mandate was created. This is read only and set by the server.

Responses

Request samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "DRAFT",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 101,
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "altReference": "ALT/22012018-24",
  • "sortCode": "200000",
  • "accountName": "CARLOS SANTANA",
  • "accountNumber": "42222222",
  • "status": "DRAFT",
  • "created": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "restrictedDate": "2019-08-24T14:15:22Z"
}

Retrieve a mandate

Retrieves details of a mandate using unique identifier.

path Parameters
id
required
integer <int64>

ID of mandate, obtained from the List all mandates call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104

Response samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Update a mandate

Updates the details of a mandate.

path Parameters
id
required
string

ID of mandate, obtained from the List all mandates call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Request Body schema: application/json
required

The mandate model.

payerId
required
integer <int64>

ID of contact (the same value as the path parameter contactId).

profileId
required
integer <int64>

The collection profile ID that this mandate is associated to.

reference
required
string

Reference of the mandate. This is the reference that is used by the paying bank to register the mandate.

sortCode
required
string

The sort code of the bank account to be debited.

accountNumber
required
string

Account number of the bank account to be debited.

id
required
integer <int64>

The ID of the mandate.

altReference
string

Alternative reference.

This reference is only used if you need to associate the mandate with some other system and the original reference cannot be used, as the key from the other system does not comply with Bacs character requirements. For example, the mandate reference is a maximum of 18 characters and the following characters are valid (&-./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ ). If you wish to associate the mandate with another entity from a system that is longer than 18 characters or contains characters not listed above, then alternative reference should be used.

accountName
string

Account name of the account to be debited.

status
required
string

Status of the mandate, where possible values are ACTIVE, SUSPENDED, CANCELLED, DELETED, DRAFT.

comments
string

Free text you wish to record against the mandate.

created
string <date-time>

Date and time when the mandate was created. This is read only and set by the server.

validationStatus
string

Ownership verification status.

Array of objects (PaymentPlan)

The list of payment plans associated to this mandate. Currently only one payment plan can be added against the mandate.

Responses

Request samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Response samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Delete a mandate

Deletes an existing mandate.

path Parameters
id
required
integer <int64>

ID of mandate, obtained from the List all mandates call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Responses

Request samples

curl -H "Content-Type: application/json" -X DELETE 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104

Update mandate status

Updates the status of a mandate.

path Parameters
mandateId
required
integer <int64>

ID of mandate, obtained from the List all mandates call.

status
required
string

The status field can have the following possible values: ACTIVE, SUSPENDED, CANCELLED, DELETED, DRAFT. DRAFT status is used as an intermediate status until all the payment plans are added and associated to the new mandate. At the end of the process of creating a new mandate, the status should be changed to ACTIVE. This is to make sure that only one correspondence is created when creating a mandate with multiple plans.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Responses

Request samples

- Activate Mandate:
curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/status/ACTIVE


- Cancel Mandate: 
curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/status/CANCEL

Response samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Create transaction

Creates a one-off transaction for the mandate.

path Parameters
mandateId
required
integer <int64>

ID of mandate, obtained from the List all mandates call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Request Body schema: application/json
required

Create a one-off transaction for the mandate.

amount
required
string

The amount of the one-off payment.

dueDate
required
string <date-time>

The due date of the one-off payment.

comments
required
string

The comment or decription of the one-off payment.

paymentType
required
string (paymentType)
Enum: "DEBIT" "REFUND" "AUDDIS"

Responses

Request samples

Content type
application/json
{
  • "amount": "45.50",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "comments": "Additional one-off collection as agreed with client.",
  • "paymentType": "DEBIT"
}

Response samples

Content type
application/json
{
  • "amount": "45.50",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "comments": "Additional one-off collection as agreed with client.",
  • "paymentType": "DEBIT"
}

Add AUDDIS instruction

Adds an AUDDIS instruction for a mandate.

path Parameters
mandateId
required
integer <int64>

ID of mandate, obtained from the List all mandates call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

Request Body schema: application/json
required

Add AUDDIS instructions for the mandate.

instructionCode
required
string

Auddis instruction.

Responses

Request samples

Content type
application/json
{
  • "instructionCode": "0N"
}

Verify an account owner

Verifies an account owner.

path Parameters
contactId
required
string

ID of contact, obtained from the List all contacts call.

Request Body schema: application/json
required

Mandate model with account and contact details.

payerId
required
integer <int64>

The ID of the payer (contact that owns this mandate).

profileId
required
integer <int64>

The collection profile ID that this mandate is associated to.

reference
required
string

Reference of the mandate. This is the reference that is used by the paying bank to register the mandate.

sortCode
required
string

The sort code of the bank account to be debited.

accountNumber
required
string

Account number of the bank account to be debited.

id
integer <int64>

The ID of the mandate.

altReference
string

Alternative reference.

This reference is only used if you need to associate the mandate with some other system and the original reference cannot be used, as the key from the other system does not comply with Bacs character requirements. For example, the mandate reference is a maximum of 18 characters and the following characters are valid (&-./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ ). If you wish to associate the mandate with another entity from a system that is longer than 18 characters or contains characters not listed above, then alternative reference should be used.

accountName
string

Account name of the account to be debited.

status
string

Status of the mandate, where possible values are ACTIVE, SUSPENDED, CANCELLED, DELETED, DRAFT.

comments
string

Free text you wish to record against the mandate.

created
string <date-time>

Date and time when the mandate was created. This is read only and set by the server.

validationStatus
string

Ownership verification status.

Array of objects (PaymentPlan)

The list of payment plans associated to this mandate. Currently only one payment plan can be added against the mandate.

Responses

Request samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Response samples

Content type
application/json
{
  • "payerId": 52,
  • "profileId": 101,
  • "reference": "RFID-22012018-24",
  • "sortCode": "200000",
  • "accountNumber": "42222222",
  • "id": 101,
  • "altReference": "ALT/22012018-24",
  • "accountName": "CARLOS SANTANA",
  • "status": "ACTIVE",
  • "comments": "Mandate was received as a hard copy.",
  • "created": "2019-08-24T14:15:22Z",
  • "validationStatus": "string",
  • "paymentPlans": [
    ]
}

Query mandate by contact ID

Executes a query to search for a mandate by contact 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.

Responses

Request samples

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

Response samples

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

Query mandate by not deleted status

Executes a query to search for mandates that are not deleted.

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 mandate by contact ID that are not deleted

Executes a query to search for mandates by contact ID that are not deleted.

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 mandate by cancelled or suspended status

Executes a query to search for mandates that are either cancelled or suspended.

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 mandate by profile ID

Executes a query to search for a mandate by profile 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 mandate between two dates that are cancelled or suspended

Executes a query to search for mandates between two dates that are either cancelled or suspended.

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 mandate by DD reference

Executes a query to search for a mandate by DD reference.

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 Plans

Payment plans are used for Direct Debit collections.

A payment plan specifies details of when payments are to be taken from a debtor's bank account.The API allows you to create, delete, validate and update your payment plans. You can retrieve individual payment plans as well as a list of all your payment plans.

List all payment plans

Returns a list of all payment plans.

path Parameters
contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/payment-plans

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment plan

Creates a new payment plan.

path Parameters
contactId
required
string

ID of contact.

mandateId
required
string

ID of mandate.

Request Body schema: application/json
required

The payment plan model.

Set to WeeklyPaymentPlan, MonthlyPaymentPlan, MonthlyPickPaymentPlan or YearlyPaymentPlan.

object (WeeklyPaymentPlan)
object (MonthlyPaymentPlan)
object (MonthlyPickPaymentPlan)
object (YearlyPaymentPlan)

Responses

Request samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Response samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Retrieve a payment plan

Retrieves details of a payment plan using unique identifier.

path Parameters
id
required
integer <int64>

ID of payment plan, obtained from the List all payment plans call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/payment-plans/32

Response samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Update a payment plan

Updates an existing payment plan.

path Parameters
id
required
string

ID of payment plan, obtained from the List all payment plans call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Request Body schema: application/json
required

The payment plan model.

Set to WeeklyPaymentPlan, MonthlyPaymentPlan, MonthlyPickPaymentPlan or YearlyPaymentPlan.

object (WeeklyPaymentPlan)
object (MonthlyPaymentPlan)
object (MonthlyPickPaymentPlan)
object (YearlyPaymentPlan)

Responses

Request samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Response samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Delete a payment plan

Deletes an existing payment plan.

path Parameters
id
required
integer <int64>

ID of payment plan, obtained from the List all payment plans call.

contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Responses

Request samples

curl -H "Content-Type: application/json" -X DELETE 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/payment-plans/32

Update payment plan status

Updates the status of payment plan.

path Parameters
paymentPlanId
required
integer <int64>

ID of payment plan, obtained from the List all payment plans call.

status
required
string

New payment plan status.

contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Responses

Request samples

- Activate plan:
curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/payment-plans/32/status/ACTIVE

- Suspend plan:
curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/contacts/52/mandates/104/payment-plans/32/status/SUSPENDED

Response samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Validate a payment plan

Validates a payment plan.

path Parameters
contactId
required
string

ID of contact, obtained from the List all contacts call.

mandateId
required
string

ID of mandate, obtained from the List all mandates call.

Request Body schema: application/json
required

The payment plan is validated and its details are updated if valid.

Set to WeeklyPaymentPlan, MonthlyPaymentPlan, MonthlyPickPaymentPlan or YearlyPaymentPlan.

object (PaymentPlan)

Responses

Request samples

Content type
application/json
{
  • "PaymentPlan": {
    }
}

Response samples

Content type
application/json
{
  • "WeeklyPaymentPlan": {
    },
  • "MonthlyPaymentPlan": {
    },
  • "MonthlyPickPaymentPlan": {
    },
  • "YearlyPaymentPlan": {
    }
}

Collection History

The API allows you to query the collection history including by status, Direct Debit reference, mandate and between two dates.

Query collection history

Executes a query for collection history.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history between dates

Executes a query for collection history between two dates.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by status

Executes a query for collection history by status.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by alternative ref between two dates

Executes a query for collection history using alternate reference and between two dates.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by profile ID between two dates

Executes a query for collection history using profile ID and between two dates.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by mandate

Executes a query for collection history by mandate.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by Direct Debit ref

Executes a query for collection history by Direct Debit reference.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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 collection history by status, payment type and between dates

Executes a query for collection history using status, payment type and between two dates.

In the response returned, the possible values for the status of an instruction are:

  • DELETED
  • FAILURE
  • INDEMNITY CLAIMED
  • PENDING
  • SUCCESS
.

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

Correspondence

Correspondence for a contact is used for Direct Debit collections.

The API allows you to execute a query to list all correspondence IDs by profile ID and status, the correspondence can then be suppressed if required.

The API also allows you to generate a report for a given correspondence and then retrieve it.

Generate report

Generates a report for a given correspondence.

path Parameters
id
required
integer <long>

ID of the correspondence which can be obtained from the Query DDM correspondence by ID and status call.

Responses

Request samples

curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/reports/generate/communication/89337

Response samples

Content type
application/json

Retrieve report

Retrieves a report for a given correspondence.

The URL for this API call is the value of the pollURL field returned in the response of the Generate report call.

path Parameters
id
required
integer <long>

Report ID which can be obtained from the Generate report call.

Responses

Request samples

curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/reporting/14410/download/PDF

Suppress correspondence

Suspends communication using communcation ID if required.

path Parameters
id
required
integer <int64>

ID of the correspondence obtained from the Query DDM correspondence by ID and status call.

Responses

Request samples

curl -H "Content-Type: application/json" -X POST 
https://uk.pt-x.com/payments-service/api/ddm/communications/2827208/suppress

Response samples

Content type
application/json
{
  • "@type": "Auditable",
  • "created": "2021-09-23T09:46:59.318",
  • "lastUpdated": "2021-10-06T10:47:47.172"
}

Query DDM correspondence

Executes a query to return the correspondence for all mandates.

Note: By default only the first 50 entries will be returned.

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 DDM correspondence by subject

Executes a query to return the correspondence by subject for all mandates.

Possible values for the subject are:

  • INDEMNITY_CLAIMED
  • CANCEL_MANDATE
  • CANCEL_MANDATE_ADDACS
  • CANCEL_MANDATE_AUDDIS
  • CHANGE_MANDATE
  • CHANGE_MANDATE_ADDACS
  • REACTIVATE_MANDATE
  • SUSPEND_MANDATE
  • NEW_MANDATE_NO_PLAN
  • NEW_MANDATE
  • ONE_OFF_PAYMENT
  • REFUND_PAYMENT
  • UNPAID_SUB_PAYMENT
  • UNPAID_SUB_REPRESENTED
  • UNPAID_PAYMENT
  • UNPAID_REPRESENTED

Notes:

  • It is possible to specify more than one subject type in the query.
  • By default only the first 50 entries will be returned.

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 DDM correspondence by ID and status

Executes a query to list all correspondence IDs by profile ID and status.

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

DDM File Import

The API allows you to import a DDM file, retrieve the result of manually importing a DDM payer or one off collection file, query the results using for example, status, file type and between two dates or file ID.

Import contacts and mandates data

Imports a file containing contacts data into PTX DDM and updates associated mandates.

path Parameters
id
required
integer <int64>

Collection profile identifier.

file
required
string

File name to import.

Responses

Request samples

curl -F 'file=@PAYER_FILE' https://uk.pt-x.com/payments-service/api/ddm/file/upload/4826/PAYER_FILE	

Response samples

Content type
application/json
{}

Import DDM file for a one off collection

Imports a DDM file for a one off collection.

path Parameters
id
required
integer <int64>

Collection profile identifier.

file
required
string

File to import.

Responses

Request samples

curl -F 'file=@PAYER_FILE' https://uk.pt-x.com/payments-service/api/ddm/file/upload/4826/ONE_OFF_PAYMENTFILE	

Response samples

Content type
application/json
{}

Retrieve import result

Retrieves the result of importing a DDM payment file.

path Parameters
id
required
integer <int64>

File identifier as generated by PTX, obtained from the URL when importing via the User Interface.

Responses

Request samples

curl -H "Content-Type: application/json" -X GET 
https://uk.pt-x.com/payments-service/api/ddm/file/9511

Response samples

Content type
application/json
{
  • "ModelId": 9511,
  • "name": "Test One Off Import Error.txt",
  • "paymentProfileId": 4826,
  • "paymentProfileName": "EXAMPLE COLLECTION PROFILE",
  • "type": "ONE_OFF_PAYMENTFILE",
  • "status": "SUCCESS",
  • "userId": "JGX3FTUOQF1PPIDQTMLF",
  • "created": "2020-05-02T16:26:06.556",
  • "lastUpdated": "2020-05-02T16:26:07.804",
  • "recordsProcessed": 4,
  • "recordsImported": 3,
  • "totalAccepted": 151200,
  • "totalRejected": 0
}

Query DDM file import result by file id

Executes a query for import result details using file 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 DDM file import results by status, file type & between two dates

Executes a query for import results using status, file type and between two dates, where file type is set to either ONE_OFF_PAYMENTFILE or PAYER_FILE.

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

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://uk.pt-x.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://uk.pt-x.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
[
  • {
    },
  • {
    }
]