Enable pagination for the /transactions endpoint

The /transactions endpoint is introducing pagination. Follow this guide to enable this feature for improved reliability and performance.

Once pagination is enabled, If you try to retrieve more than 1000 transactions at once, the response that you receive will be incomplete. Fetch subsequent pages using the cursor to the next page returned from the response.

You can retrieve a maximum of 31 days of data at once. To fetch more, perform multiple queries with different from and to values (and fetch all pages).

Enable Pagination

Enable this feature by adding a header (tl-enable-pagination: true) in the request to merchant-accounts/{id}/transactions endpoint. If you have done this successfully, the pagination object will be present in the response.

1. Send a GET request with the required bearer token and from and to values (optionally also type).
2. Check if pagination.next_cursor is present. If not, this is the end of all transactions.
3. Otherwise, pass the cursor in a subsequent request with a cursor query string (Ensure this is correctly encoded. Otherwise you may get a 400 error with the error message Invalid cursor).
4. Inspect the pagination.next_cursor again.

Below is a diagram that illustrates the process.

Below are examples of successful responses where the pagination object is present.

{  
	"items": [  
		{"type": "payout", ... },  
		{"type": "external_payment", ... },  
		{"type": "merchant_account_payment" ... },  
    // truncated  
	],  
	"pagination": {  
		"next_cursor": "eyJkYXk...X0="  
  }  
}

{
	"items": [
		{"type": "payout", ... },
		{"type": "external_payment", ... },
		{"type": "merchant_account_payment" ... },
	],
	"pagination": {
     // no next_cursor
  }
}

Below is an example of an error response. This error is caused by setting your from and to values so that the range between them is greater than 31 days.

{
  "type": "https://docs.truelayer.com/docs/error-types#invalid-parameters",
  "title": "Invalid Parameters",
  "status": 400,
  "trace_id": "0f16d77a-be67-4128-b837-56142e064920",
  "detail": "Invalid value for parameter from/to: Date range exceeds the maximum allowed duration of 31 days",
  "errors": {
    "from/to": [
      "Date range exceeds the maximum allowed duration of 31 days"
    ]
  }
}

A few validation errors can occur when you specify a cursor query string that is not compatible with other parameters:

1. The cursor does not match the merchant account ID specified in the path parameter (id)
2. The cursor does not match the type -query string specified.
3. The cursor is invalid or not URL encoded.