Track transactions

Use our API to get updates about transactions in your balance platform.

To keep track of funds movements in your balance platform, you can:

Get updates through webhooks.

Make API requests to keep track of transactions.

With the Transactions API, you can query the transactions for your whole balance platform, a particular account holder, or balance account.

Get a list of transactions

To get a list of transactions, make a GET /transactions request with the following query parameters:

Either balancePlatform, accountHolderId, or balanceAccountId
createdSince: Transactions created after this date and time are included in the response.
createdUntil: Transactions created before this date and time are included in the response.
(Optional) limit: The number of items returned per page.

For the date fields, the date-time value must be in ISO 8601 format. For example, 2021-05-30T15:07:40Z.

Example GET /transactions request

 curl https://balanceplatform-api-test.adyen.com/btl/v4/transactions?accountHolderId=AH00000000000000000000001&createdUntil=2021-10-05&limit=4&accountHolder&createdSince=2015-10-01 \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X GET \
-d ''

The response includes:

A data array containing all the transactions that match the query parameters. You can refer to certain objects to identify incoming and outgoing transactions.
A _links object containing links to the next or previous page when applicable. To page through the results, add the cursor value as a query parameter in your next request.

Example GET /transactions response

 {
    "data": [
        {
            "balancePlatform": "YOUR_BALANCE_PLATFORM",
            "creationDate": "2023-08-10T14:51:20+02:00",
            "description": "Your description for the payout",
            "id": "EVJN42272224222B5JB8BRC84N686ZEUR",
            "accountHolder": {
                "description": "Your description for the account holder",
                "id": "AH00000000000000000000001"
            },
            "amount": {
                "currency": "USD",
                "value": -1000
            },
            "balanceAccount": {
                "description": "Your description for the account holder",
                "id": "BA00000000000000000000001"
            },
            "bookingDate": "2023-08-10T14:51:33+02:00",
            "status": "booked",
            "transfer": {
                "categoryData": {
                    "priority": "regular",
                    "type": "bank"
                },
                "id": "3JNC3O5ZVFLLGV4B",
                "reference": "Your internal reference for the transfer"
            },
            "referenceForBeneficiary": "Your reference sent to the beneficiary",
            "valueDate": "2023-08-10T14:51:20+02:00"
        },
        {
            "balancePlatform": "YOUR_BALANCE_PLATFORM",
            "creationDate": "2023-08-10T15:34:31+02:00",
            "description": "Your description for the transfer",
            "id": "EVJN4227C224222B5JB8G3Q89N2NB6EUR",
            "accountHolder": {
                "description": "Your description for the account holder",
                "id": "AH00000000000000000000001"
            },
            "amount": {
                "currency": "USD",
                "value": 123
            },
            "balanceAccount": {
                "description": "Your description for the account holder",
                "id": "BA00000000000000000000001"
            },
            "bookingDate": "2023-08-10T15:34:40+02:00",
            "status": "booked",
            "transfer": {
                "id": "48POO45ZVG11166J",
                "reference": "Your internal reference for the transfer"
            },
            "valueDate": "2023-08-10T15:34:31+02:00"
        },
        {
            "balancePlatform": "YOUR_BALANCE_PLATFORM",
            "creationDate": "2023-08-11T13:45:46+02:00",
            "description":"Your description for the transfer",
            "id": "EVJN4227C224222B5JBD3XHF8P3L8GUSD",
            "accountHolder": {
                "description": "Your description for the account holder",
                "id": "AH00000000000000000000001"
            },
            "amount": {
                "currency": "USD",
                "value": -10000
            },
            "balanceAccount": {
                "description": "Your description for the account holder",
                "id": "BA00000000000000000000001"
            },
            "bookingDate": "2023-08-11T13:45:57+02:00",
            "status": "booked",
            "transfer": {
                "categoryData": {
                    "priority": "internal",
                    "type": "internalTransfer"
                },
                "id": "48RTTW5ZVT8KU9DV",
                "reference": "The sender's reference for the transfer"
            },
            "valueDate": "2023-08-11T13:45:46+02:00"
        },
        {
            "balancePlatform": "YOUR_BALANCE_PLATFORM",
            "creationDate": "2023-08-11T13:45:51+02:00",
            "description": "The sender's description for the transfer",
            "id": "EVJN42272224222B5JBD3XJGHF4J26USD",
            "accountHolder": {
                "description": "Your description for the account holder",
                "id": "AH00000000000000000000001"
            },
            "amount": {
                "currency": "USD",
                "value": 1000
            },
            "balanceAccount": {
                "description": "Your description for the account holder",
                "id": "BA00000000000000000000001"
            },
            "bookingDate": "2023-08-11T13:45:58+02:00",
            "status": "booked",
            "transfer": {
                "id": "48TYZO5ZVT8M1K47",
                "reference": "The sender's reference for the transfer"
            },
            "valueDate": "2023-08-11T13:45:51+02:00"
        }
    ],
    "_links": {
        "next": {
            "href": "https://balanceplatform-api-test.adyen.com/btl/v4/transactions?balancePlatform=TestBalancePlatform&createdUntil=2023-08-20T13%3A07%3A40Z&createdSince=2023-08-10T10%3A50%3A40Z&cursor=S2B-c0p1N0tdN0l6RGhYK1YpM0lgOTUyMDlLXElyKE9LMCtyaFEuMj1NMHgidCsrJi1ZNnhqXCtqVi5JPGpRK1F2fCFqWzU33JTojSVNJc1J1VXhncS10QDd6JX9FQFl5Zn0uNyUvSXJNQTo"
        }
    }
}

If you want to only get details for a particular transaction, get the specific transaction ID and make a GET /transactions/{id} request.

Identify incoming and outgoing funds

Refer to the following fields and objects of the API response to find out if a transaction is outgoing or incoming.

Field	Incoming funds	Outgoing funds
`amount`	Has a positive `value`, meaning funds are added to the balance account.	Has a negative `value`, meaning funds are deducted from the balance account.
`transfer.reference`	The reference from the sender, if they sent any.	The reference that you sent in the `/transfers` request.
`status`	The status of the transaction. It can be: pending: The funds have not been added yet to the balance account. Check the `valueDate` to know when the funds will be available. booked: The funds have been added to the balance account.	The status of the transaction. It can be: pending: The funds are reserved to be deducted from the balance account. Check the `valueDate` to know when the funds will be deducted. booked: The funds have been deducted from the balance account.

Both incoming and outgoing transactions can be a result of external or internal transfers. The following subsections show example responses for external and internal transactions

External transactions

These transactions result from external transfers. For example:

A payment from a purchase in your platform results in an incoming external transaction.
A payout to one of your users results in an outgoing external transaction.

The following tabs show example responses that you would get when making a request to get incoming or outgoing external transactions.

After making a successful GET /transactions or GET /transactions/{id} request, you get the following information:

Incoming external transaction

 {
    "id": "EVJN00000000000000000000000001EUR",
    "amount": {
        "value": 10000,
        "currency": "EUR"
    },
    "status": "booked",
    "transfer": {
        "categoryData": {
            "modificationMerchantReference": "MRef#000001",
            "modificationPspReference": "PPKFQ89R6QRXGN82",
            "paymentMerchantReference": "Payment reference",
            "platformPaymentType": "BalanceAccount",
            "pspPaymentReference": "CWBC43ZX2VTFWR82",
            "type": "platformPayment"
        },
        "id": "3JW8PC5ZVV06067J",
        "reference": "automatically-generated-reference"
    },
    "valueDate": "2023-08-11T16:19:35+02:00",
    "bookingDate": "2023-08-11T16:43:46+02:00",
    "creationDate": "2023-08-11T16:43:46+02:00",
    "accountHolder": {
        "id": "AH00000000000000000000001",
        "description": "Your description of the account holder"
    },
    "balanceAccount": {
        "id": "BA00000000000000000000001",
        "description": "Your description of the balance account"
    },
    "balancePlatform": "YOUR_BALANCE_PLATFORM"
}

Internal transactions

These transactions result from internal transfers between balance accounts. The following tabs show example responses that you would get when making a request to get incoming or outgoing internal transactions.

After making a successful GET /transactions or GET /transactions/{id} request, you get the following information:

Incoming internal transaction

 {
    "id": "EVJN00000000000000000000000001EUR",
    "amount": {
        "value": 10000,
        "currency": "EUR"
    },
    "status": "booked",
    "transfer": {
        "categoryData": {
            "type": "internal"
        },
        "id": "3JW8PC5ZVV06067J",
        "reference": "An internal reference for the transfer"
    },
    "valueDate": "2023-08-11T16:19:35+02:00",
    "bookingDate": "2023-08-11T16:43:46+02:00",
    "creationDate": "2023-08-11T16:43:46+02:00",
    "description": "The sender's description of the transfer",
    "referenceForBeneficiary": "The sender's reference for the beneficiary",
    "accountHolder": {
        "id": "AH00000000000000000000001",
        "description": "Your description of the account holder"
    },
    "balanceAccount": {
        "id": "BA00000000000000000000001",
        "description": "Your description of the balance account"
    },
    "balancePlatform": "YOUR_BALANCE_PLATFORM"
}

Booking and value dates

For every transaction returned in the API response, you receive two date fields: the bookingDate and the valueDate.

The dates in these fields may be different when a fund transfer is pending. For example, when you pay out to a transfer instrument after bank cutoff times, the funds are reserved but are not yet deducted. In this scenario, the dates will be:

bookingDate: The date when Adyen receives the transfer request.
valueDate: A future date, when the funds are expected to be deducted from the balance account.

The transaction will also have a pending status.

When the funds are finally deducted from the account at the specified valueDate, the status of the transaction changes to booked.