Bottomline BACS payments

ACH bank transfers for the UK

Demo

Editor page here and run mode here. The actual functionality is on a private plugin (Bottomline BACS).

Credentials: u: username p: password

High level overview

The app has 3 types of calls

  1. Authentication

  2. Payments/Payment logic

  3. Queries (get data)

The Authentication calls must be run every time a payment or query call is run.

For testing, use the URL , and for live calls use the URL X as the base of your API call. This is built into each plugin call so that you can set up the logic to work in both production and development.

Technical Details

Authentication

Authentication headers that are generated are valid for 10 minutes, or until 10 minutes after the last successful API call runs. (I.e. if you keep running another API call every 9 minutes, you'll never need to regenerate the headers... but that's not necessary).

If you regenerate the headers, the new ones will work even if the previous keys haven't expired, and the previous keys will then be invalid.

To use this flow: run the Handshake action to generate the X-CSRF and Cookie headers, and then use the Authenticate action to re-generate the X-CSRF header and generate the com.bottomline.auth.token header.

Payments

Payments happen in this order:

  1. Payment Batch is created (Create Batch Payment)

  2. Payment Instructions are created (Create Payment Instruction)

    1. We can have multiple Payments in one Batch, and each Payment Instruction contains details about payments.

  3. A BACS request is submitted (BACS Submission)

    1. Unsure if this actually carries out the BACS transfer, or if it submits the transfer and some user will need to approve it manually within the PTX dashboard.

When generating IDs for the Payment Batch API Call and the Payment Instructions API Call, I recommend starting with the ID 100,000 and counting upwards, since I've used some of the numbers below 100,000 to test. It seems that these IDs are discarded immediately after sending, but if we try to create 2 Batch Payments or 2 Payment Instructions with the same ID, the API throws an error. In any case, the API response to this call gives the real ID that has been assigned by the server, which we should 1) use in the other calls and 2) save in the database for reference.

The BACS Submission returns an empty body, so no data needs to be saved from the response.

Queries

These are basically database searches, but they search Bottomline's database for our activity. The following are set up in the plugin:

  1. List Payment Profiles

  2. Export BACS Payment Instructions (Query)

  3. Get BACS Payment Instructions (One Batch Query)

  4. Export BACS Submissions (Query)

There are 50 different data types that can be queried, but we don't seem to be using most of them, and some of them return static data types (like the Transaction Type query).

Prior to running the BACS Submission API Call (to actually submit a payment), it may be wise to ask the user to check the payment instructions associated with a batch query using the Get BACS Payment Instructions call.

Check out the test app to see how to use these.

Note: These calls might time out, occasionally they run very slowly, sometimes they return almost immediately (results seem to be cached).

For more techincal notes: https://developer.pt-x.com/payments/#operation/createBatch