The range between from and to cannot be more than 31 days if there are more than 2,000 transactions.
cursor
No
Query parameter
String
This is an optional parameter that is never required in an initial request to the transactions endpoint.
This is only used if you receive more than 2,000 transactions in your response, meaning it is paginated. For a paginated response , use this to retrieve the next page of results by passing the value of next_cursor in the preceding response.
type
No
Query parameter
String
The type of transaction to return from the merchant account.
Can have a value of payment for payments, or payout for payouts
If omitted, the endpoint returns both payments and payouts.
This is an example of a request to get a list of transactions between the dates of 1 April 2024 until 17 April 2024:
If the response returns more than 2,000 transactions, the result is paginated and you need to navigate through the results.
Note that the id returned for each item is a transaction id, not a payment or payout id, which is included in a separate payment_id or payout_id object. However, a payout_id is the same as the associated transaction id.
Pagination for the /transactions endpoint
If your request would return more than 2,000 transactions, the /v3/merchant-account/{id}/transactions endpoint returns paginated responses, which each contain 2,000 transactions and a next_cursor string.
📘
You may need to enable pagination in older integrations
Pagination became the default behaviour for the /v3/merchant-account/{id}/transactions endpoint in December 2023. If you created your Console account before then, you may need to manually include pagination for your requests to this endpoint. If you don't enable pagination, you receive all transactions, but may receive a 500 error due to the 12-second timeout for requests.
To include pagination, include the tl-enable-pagination:true header in any requests you make. You receive a paginated response if you do this correctly.
Expand to learn more about enabling pagination in older integrations
To use pagination in an older integration, you should:
Send a GET request with:
A suitable access_token for your merchant account.
The tl-enable-pagination:true header.
Appropriate dates for the from and to parameters.
Optionally, a value of payment or payout for the type parameter.
Check if the response contains pagination.next_cursor. If it doesn't skip to step 4.
If the response contains pagination.next_cursor, pass the value from this in a subsequent request within the cursor parameter.
If it doesn't, this is the end of all transactions.
Take the value from pagination.next_cursor in the response and pass it within the cursor parameter in a new request, within the cursor parameter. Repeat this process.
Ensure the cursor parameter is correctly encoded, or you may get a 400 error, invalid cursor.
When the response no longer contains the pagination.next_cursor object, you have retrieved all transactions.
An example of the flow when you retrieve paginated responses for the /v3/merchant-accounts/{id}/transactions endpoint.
Note that pagination doesn't apply to transactions prior to 1 September 2022. However, you can use the from and to parameters to limit the number of transactions returned.
Example paginated responses
This code block contains truncated code blocks that show what a response looks like if it:
Is paginated and there is a subsequent page you must retrieve.
Is paginated but is the final page, so there are no further pages.
