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 10 minutes if it is not used 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
This will return a header similar to the following:
Response Header:

X-Frame-Options:SAMEORIGIN
X-CSRF:
Vary:Accept-Encoding
Connection:close
Transfer-Encoding:chunked
Cache-Control:no-cache, no-store, must-revalidate, pre-check=0, post-check=0
Content-Type:application/json
Date:Mon, 7 Jan 2019 14:17:30 GMT
Expires:-1
Set-Cookie:JSESSIONID=; path=/; HttpOnly

Extract the JSESSIONID cookie (from the Set-Cookie field in the response header, extracting the ID only) and the CSRF Token (from the X-CSRF field in the response header); these will need to be used in the login request header below.

Authenticate

Make a POST call to this URL:

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

Note: It may not be necessary to specify HTTP/1_1 in the URL.

The body contains the user email and password details in the format below:

{ "loginTokens": [{ "key": "com.bottomline.security.provider.login.email",
"value": "user@example.com" }, {
"key": "com.bottomline.security.provider.login.password",
"value": "password"
}],
"apiVersion": "{\"major\": \"1\",\"minor\": \"0\",\"patch\": \"0\",\"build\": \"0\"}",
"purpose": "cpay-auth",
"tokenLocation": "HEADER"
}

Make the call with request headers in the format below, containing the session ID and CSRF token returned from the handshake.

User-Agent: Java/1.7.0_51
Content-Type: application/json
Cookie: JSESSIONID=
X-CSRF:

On success, request headers containing a new X-CSRF token and the auth.token will be returned in a format similar to below:

X-Frame-Options:SAMEORIGIN
com.bottomline.auth.token:
X-CSRF:
Content-Length:0
Cache-Control:no-cache, no-store, must-revalidate, pre-check=0, post-check=0
Content-Type:text/plain
Date:Mon, 7 Jan 2019 14:17:30 GMT Expires:-1

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

Using the API

API calls can now be made as per the documentation. All 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.

Content-Type: application/json
Cookie: JSESSIONID=
X-CSRF:
com.bottomline.auth.token:

Data Types

String

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

Payment Batches

Payment batches are used for making payments.

A payment batch contains payment instructions details. The API allows you to create a batch which will upload the payment into the PTX system. You can create a batch template and create a batch from the template.

Create a new payment batch

Creates a new payment batch.

Request Body schema: application/json

The MdeHeader

id
int <int64>

Unique identifier of batch file.

submissionId
int <int64>

Unique identifier of submission file.

application
string <string>

Unique identifier of the selected payment profile.

applicationName
string <string>

The name of the selected Payment Profile.

entries
Array of objects (schema6)

A list of Payment Instructions included to this batch file.

applicationDescription
string <string>

The name and Service User Number of the selected payment profile.

paymentDate
string <date-time>

The payment date of the instruction.

type
string <string>
Default: "DBACS"

The type of instruction.

description
string <string>

The batch file name.

debitCount
int <int32>

Count of total debits.

debitTotal
int <int64>

Total amount of debits.

creditCount
int <int32>

Count of total credits.

creditTotal
int <int32>

Total amount of credits.

Responses

200

OK

400

Bad Request. The server was unable to understand the request due to invalid syntax.

401

Unauthorized. You need to login first in order to perform this action.

403

Forbidden. You are not entitled to perform this action.

404

Not Found. The server was not able to find the item you were looking for.

500

Internal Server Error. The server encountered an error which prevented it from processing your request.

503

Service Unavailable. The server is not currently available to process requests.

post /bacs/batches
https://uk.pt-x.com/payments-service/api/bacs/batches

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 100,
  • "submissionId": 99,
  • "application": 33,
  • "applicationName": "Direct MDE Profile",
  • "entries":
    [
    ],
  • "applicationDescription": "Direct MDE Profile {100124}",
  • "paymentDate": "2019-08-05T08:45:19Z",
  • "type": "DBACS",
  • "description": "DirectMDEProfile-1515062817535",
  • "debitCount": 3,
  • "debitTotal": 623.45,
  • "creditCount": 14,
  • "creditTotal": 125650.9
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 100,
  • "submissionId": 99,
  • "application": 33,
  • "applicationName": "Direct MDE Profile",
  • "entries":
    [
    ],
  • "applicationDescription": "Direct MDE Profile {100124}",
  • "paymentDate": "2019-08-05T08:45:19Z",
  • "type": "DBACS",
  • "description": "DirectMDEProfile-1515062817535",
  • "debitCount": 3,
  • "debitTotal": 623.45,
  • "creditCount": 14,
  • "creditTotal": 125650.9
}

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

200

OK

400

Bad Request. The server was unable to understand the request due to invalid syntax.

401

Unauthorized. You need to login first in order to perform this action.

403

Forbidden. You are not entitled to perform this action.

404

Not Found. The server was not able to find the item you were looking for.

500

Internal Server Error. The server encountered an error which prevented it from processing your request.

503

Service Unavailable. The server is not currently available to process requests.

post /bacs/batches/{batchId}/template
https://uk.pt-x.com/payments-service/api/bacs/batches/{batchId}/template

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "templateName": "MyWeeklyBatchFile",
  • "batchId": 100
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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

200

OK

400

Bad Request. The server was unable to understand the request due to invalid syntax.

401

Unauthorized. You need to login first in order to perform this action.

403

Forbidden. You are not entitled to perform this action.

404

Not Found. The server was not able to find the item you were looking for.

500

Internal Server Error. The server encountered an error which prevented it from processing your request.

503

Service Unavailable. The server is not currently available to process requests.

post /bacs/batches/{templateId}/template/batch
https://uk.pt-x.com/payments-service/api/bacs/batches/{templateId}/template/batch

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "id": 100,
  • "submissionId": 99,
  • "application": 33,
  • "applicationName": "Direct MDE Profile",
  • "entries":
    [
    ],
  • "applicationDescription": "Direct MDE Profile {100124}",
  • "paymentDate": "2019-08-05T08:45:20Z",
  • "type": "DBACS",
  • "description": "DirectMDEProfile-1515062817535",
  • "debitCount": 3,
  • "debitTotal": 623.45,
  • "creditCount": 14,
  • "creditTotal": 125650.9
}

Payment Instructions

Payment instructions are used for making payments.

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

Create an instruction

Creates a new instruction.

Request Body schema: application/json

The MdeEntry

id
integer <int64>

Unique identifier of payment instruction entry.

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.

index
integer <int64>

The index identifier of the instruction within the batch file.

transactionType
string <string>

Transaction type of the instruction.

transactionTypeCode
string <string>

Transaction code of the instruction.

sortCode
string <string>

The destination sort code.

accountNumber
string <string>

The destination account number.

batchId
integer <int64>

Unique identifier of batch for update.

reference
string <string>

The payment reference.

amount
string <amounts>

The payment amount.

paymentDate
string <date-time>

The payment date of the instruction.

type
string <string>
Default: "DBACS"

The type of instruction.

name
string <string>

The destination account name.

rti
string <string>

The pre-submission HMRC RTI validation.

isDDMEntry
boolean
Default: false

Alternative identifier for DDM instructions.

Responses

200

Request processed

400

Bad Request. The server was unable to understand the request due to invalid syntax.

401

Unauthorized. You need to login first in order to perform this action.

403

Forbidden. You are not entitled to perform this action.

404

Not Found. The server was not able to find the item you were looking for.

500

Internal Server Error. The server encountered an error which prevented it from processing your request.

503

Service Unavailable. The server is not currently available to process requests.

post /bacs/instructions
https://uk.pt-x.com/payments-service/api/bacs/instructions

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 1056,
  • "paymentType": "Bacs",
  • "included": true,
  • "index": 42,
  • "transactionType": 0,
  • "transactionTypeCode": 99,
  • "sortCode": 200000,
  • "accountNumber": 42222222,
  • "batchId": 101,
  • "reference": "Reference-101",
  • "amount": "402.35",
  • "paymentDate": "2019-08-05T08:45:20Z",
  • "type": "DBACS",
  • "name": "JON SMITH",
  • "rti": "",
  • "isDDMEntry": false
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 1056,
  • "paymentType": "Bacs",
  • "included": true,
  • "index": 42,
  • "transactionType": 0,
  • "transactionTypeCode": 99,
  • "sortCode": 200000,
  • "accountNumber": 42222222,
  • "batchId": 101,
  • "reference": "Reference-101",
  • "amount": "402.35",
  • "paymentDate": "2019-08-05T08:45:20Z",
  • "type": "DBACS",
  • "name": "JON SMITH",
  • "rti": "",
  • "isDDMEntry": false
}

Delete an instruction

Deletes an instruction.

path Parameters
entryId
required
integer <int64>

Unique identifier of entry for the deletion.

Responses

204

No Content. The request was successful but no additional content to return.

400

Bad Request. The server was unable to understand the request due to invalid syntax.

401

Unauthorized. You need to login first in order to perform this action.

403

Forbidden. You are not entitled to perform this action.

404

Not Found. The server was not able to find the item you were looking for.

500

Internal Server Error. The server encountered an error which prevented it from processing your request.

503

Service Unavailable. The server is not currently available to process requests.

delete /bacs/instructions/{entryId}
https://uk.pt-x.com/payments-service/api/bacs/instructions/{entryId}

Request samples

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

Response samples

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

Edit an instruction

Updates an instruction.

path Parameters
entryId
required
integer <int64>

Unique identifier of entry for the update.

Request Body schema: application/json

Unique identifier of entry for the upda