API (1.0)

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

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

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

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

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

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.

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

GET /payments-service/api/security/handshake

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

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

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

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

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

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

Ensure to include the following additional, mandatory headers:

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

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

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

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

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

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

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

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

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

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

Example call

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

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

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

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

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

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.

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

Payment profiles are used for making payments.

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

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

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