API Workflow & Setup
This document outlines the standard (Happy-path) flow for the BTD API. It explains how to retrieve the transaction details of a batch, and how to retrieve the other Id's (account en batch) that you need to be able to do this.
To test error scenarios, see Try it Out (Sandbox).
Before you begin
Before you request batch transaction details, you should to meet the following requirements.
Sandbox Requirements
- Set up a sandbox account
- Set up sandbox application and subscription to:
- Business Account Insight Sandbox
- Batch Transaction Details Sandbox
- Set up your Mutual TLS connection, you can find our example certificates for sandbox here.
- Set up your signing flow, you can find our example certificates for sandbox here.
- Set up your Oauth flow
Production Requirements
- Set up a production account. To get a production account, see Go to Production
- Set up production application and subscription to:
- Business Account Insight
- Batch Transaction Details
- Set up your Mutual TLS connection with your EV SSL certificate
- Set up your signing flow with your EV SSL certificate
- Set up your OAuth flow
Required Headers
You are required to sign the payload for GET (Batch transactions for a specific consented payment account) requests.
Read our Validate Signing Requests documentation for a detailed description of our signing method.
Required headers to include in your requests are:
| Name | Description | Format |
|---|---|---|
| Date | The date in a RFC-compliant date/time format. | String |
| Digest | The digest is a base64 encoded hash of the body. | String |
| X-Request-ID | The X-Request-ID is a UUID generated by you. | UUID |
| Signature | The signature is the signing string signed with your private key. | String |
| Signature-Certificate | The signature certificate is the public part of your EV SSL signing certificate. | String |
| X-IBM-Client-ID | The X-IBM-Client-ID is a UUID generated by your application. | UUID |
| Authorization | The Authorization header should include your access token. | String |
To retrieve the transaction details of a specific batch for a payment account, your request must include both an account-id and a batch-entry-reference.
Step 1 - Retrieve account-id
Endpoint:
Read Account List
GET /payments/insight/accounts
Purpose: Before making a request to batch transactions endpoint, you must obtain the account-id by using the Read Account List endpoint of the Business Account Insight - Accounts API.
Step 2 - Retrieve batch-entry-reference
Endpoint:
Read Transactions
GET /payments/insight/accounts/{account-id}/transactions
Purpose: You can obtain the batch-entry-reference by using the Read Transactions endpoint of the Business Account Insight - Transactions API using the account-id.
Step 3 - Retrieve transaction details of a specific batch
Endpoint:
Batch transactions for a specific consented payment account
GET /payments/insight/accounts/{account-id}/batch-details/{batch-entry-reference}
Purpose: Retrieves all transactions including details for a specific batch using the account-id and batch-entry-reference.
In the response, you receive a list of transactions for a specific batch.
Each response is paginated with a maximum of 500 transactions per page. You can use the pageNumber parameter to retrieve a next page of transactions for that batch.
The total number of transactions and the corresponding amount for the batch should match the booking returned by the Business Account Insight - Transactions API. Any rejections are booked as separate return bookings and are not be visible in this response.