Get your merchant account transactions or payment sources

Use merchant account endpoints to see a list of payments in and out of your merchant account.

Get transactions for a merchant account

To get a list of transactions for a merchant account, make a GET request to the /v3/merchant-accounts/{id}/transactions endpoint.

Get transactions request

When you make your request, you can specify the following parameters to determine which transactions to return:

ParameterRequired?Parameter typeFormatDescription
{id}YesPath parameterStringYou must provide the id of the merchant account to get transactions for as a path parameter in your request.
fromYesQuery parameterTimestampThe start time to start retrieving transactions from. This is inclusive, so transactions that occurred on this second are included in the response.

This should be an ISO-8601 format timestamp. This is a format of:
YYYY-MM-DDTHH:MM:SS±HHMM

The range between from and to cannot be more than 31 days if there are more than 2,000 transactions.
toYesQuery parameterTimestampThe end time to stop retrieving transactions from. This is inclusive, so transactions that occurred on this second are included in the response.

This should be an ISO-8601 format timestamp. This is a format of:
YYYY-MM-DDTHH:MM:SS±HHMM

The range between from and to cannot be more than 31 days if there are more than 2,000 transactions.
cursorNoQuery parameterStringThis 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.
typeNoQuery parameterStringThe 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:

curl --request GET \
  --url 'https://api.truelayer-sandbox.com/v3/merchant-accounts/200552da-13da-43c5-a9ba-04ee1502ac57/transactions?from=2024-04-01T13%3A13%3A40Z&to=2024-04-17T13%3A42%3A32.846Z' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Idempotency-Key: {random_UUID}' \
  --header 'Tl-Signature: {signature}'

Get transactions response

This is an example of the response you receive when you make a request to the /v3/merchant-accounts/{id}/transactions endpoint and it returns less than 2,000 transactions.

{
  "items": [
    {
      "type": "merchant_account_payment",
      "id": "string",
      "currency": "GBP",
      "amount_in_minor": 0,
      "status": "settled",
      "settled_at": "string",
      "payment_source": {
        "id": "e2b41c9d-176k-67aa-b2da-fe1a2b97253c",
        "account_holder_name": "string",
        "account_identifiers": [
          {
            "type": "sort_code_account_number",
            "sort_code": 560029,
            "account_number": 26207729
          },
          {
            "type": "iban",
            "iban": "GB32CLRB04066800012315"
          }
        ]
      },
      "payment_id": "0afd1f6a-f611-48ce-9488-321129bb3a70"
    },
    {
      "type": "external_payment",
      "id": "string",
      "currency": "GBP",
      "amount_in_minor": 0,
      "status": "settled",
      "settled_at": "string",
      "remitter": {
        "account_holder_name": "string",
        "reference": "string",
        "account_identifiers": [
          {
            "type": "sort_code_account_number",
            "sort_code": 560029,
            "account_number": 26207729
          },
          {
            "type": "iban",
            "iban": "GB32CLRB04066800012315"
          }
        ]
      },
      "return_for": {
        "type": "identified",
        "returned_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
      }
    },
    {
      "type": "payout",
      "id": "string",
      "currency": "GBP",
      "amount_in_minor": 0,
      "status": "pending",
      "created_at": "string",
      "beneficiary": {
        "type": "external_account",
        "reference": "string",
        "account_holder_name": "string",
        "account_identifiers": [
          {
            "type": "sort_code_account_number",
            "sort_code": 560029,
            "account_number": 26207729
          },
          {
            "type": "iban",
            "iban": "GB32CLRB04066800012315"
          }
        ]
      },
      "context_code": "withdrawal",
      "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
    },
    {
      "type": "payout",
      "id": "string",
      "currency": "GBP",
      "amount_in_minor": 0,
      "status": "executed",
      "created_at": "string",
      "executed_at": "string",
      "beneficiary": {
        "type": "external_account",
        "reference": "string",
        "account_holder_name": "string",
        "account_identifiers": [
          {
            "type": "sort_code_account_number",
            "sort_code": 560029,
            "account_number": 26207729
          },
          {
            "type": "iban",
            "iban": "GB32CLRB04066800012315"
          }
        ]
      },
      "context_code": "withdrawal",
      "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
      "returned_by": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
    },
    {
      "type": "refund",
      "id": "string",
      "currency": "GBP",
      "amount_in_minor": 0,
      "status": "pending",
      "created_at": "string",
      "executed_at": "string",
      "beneficiary": {
        "type": "payment_source",
        "payment_source_id": "string",
        "user_id": "string",
        "reference": "string",
        "account_holder_name": "string",
        "account_identifiers": [
          {
            "type": "sort_code_account_number",
            "sort_code": 560029,
            "account_number": 26207729
          },
          {
            "type": "iban",
            "iban": "GB32CLRB04066800012315"
          }
        ]
      },
      "context_code": "withdrawal",
      "refund_id": "43d12d0f-d775-410f-aaff-482200c17017",
      "payment_id": "0afd1f6a-f611-48ce-9488-321129bb3a70",
      "returned_by": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
    }
  ],
  "pagination": {
    "next_cursor": "bWFuZGF0ZXM6MmUwNDk0MTMK"
  }
}

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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.
{
  "items": [
    {
      "type": "payout",
      "id": "dd0b9f0c-b969-4eb6-94d4-828b147ac459"
    },
    {"type": "external_payment",
     "id": "8dbf94e6-f122-4554-a6f2-f9e463c9f1fd"
    },
    // Truncated  
  ],  
  "pagination": {  
    "next_cursor": "eyJwYWdpbmciOnsiYXJ0aWNsZU5hbWUiOiJhcnRpY2xlMSIsImxhc3ROYW1lIjoiYXJ0aWNsZTEiLCJhZ2UiOjE5LCJjb2RlIjoiY29kZTEifX0="
  }
}
{
  "items": [
    {
      "type": "payout",
      "id": "dd0b9f0c-b969-4eb6-94d4-828b147ac459"
    },
    {"type": "external_payment",
     "id": "8dbf94e6-f122-4554-a6f2-f9e463c9f1fd"
    },
    // Truncated  
  ],  
  "pagination": {  
    //No next_cursor
  }
}

Incorrect cursor errors

The following circumstances can lead to errors with the cursor parameter:

  • The cursor does not match the merchant account ID you specified in the {id} path parameter.
  • The cursor does not match the type query string you specified.
  • The cursor is invalid or not URL-encoded.

Retrieve payment sources for a merchant account

To get all of the payment sources that have paid into a merchant account from a single user_id, make a GET request to the /v3/merchant-accounts/{id}/payment-sources endpoint.

Your request should include two parameters:

  • The merchant account id you want to get payment sources for, as a path parameter.
  • The user id to get the payment sources for, as a query parameter in the format ?user_id={id}.

This is an example of a request to get all the payment sources for a user:

curl --request GET \
     --url 'https://api.truelayer-sandbox.com/v3/merchant-accounts/id/payment-sources?user_id=f61c0ec7-0f83-414e-8e5f-aace86e0ed35' \
     --header 'Authorization: Bearer {access_token}' \
     --header 'Idempotency-Key: {random_UUID}' \
     --header 'Tl-Signature: {signature}'

The response contains the following information for each payment source:

  • The payment source id, which you can use to initiate a closed-loop payout.
  • The name of the account holder.
  • The account identifier, or payment details, used for the payment.

This is an example of the format of the response:

{
  "items": [
    {
      "id": "e2b41c9d-176k-67aa-b2da-fe1a2b97253c",
      "account_holder_name": "Jonathan Sandbridge",
      "account_identifiers": [
        {
          "type": "sort_code_account_number",
          "sort_code": 560029,
          "account_number": 26207729
        },
        {
          "type": "iban",
          "iban": "GB32CLRB04066800012315"
        }
      ]
    }
  ]
}