Merchant account payments

Learn about using merchant accounts to receive, make payouts, refunds, and withdrawals with Payments API v3.

A merchant account is a real bank account managed by TrueLayer on your behalf. You can use Payments API v3 to make payments into and withdrawals out of your merchant account.

When should you set up a merchant account

If you want to process closed-loop payments, you need to set up your merchant account. If you want to use Payments API v3 to only process open-loop payments, then you don't have to since we don't need to make withdrawals from a TrueLayer-managed bank account.

We use payment statuses to let you know about the different stages in the journey of a payment. When you make a payment to your merchant account, you get access to one more payment status called Settled. Settled indicates that the payment is in your merchant account and is safe to use.

31333133

If a payment resource is created with beneficiary type MerchantAccount, funds will be transferred to the Truelayer-managed merchant account. Once Truelayer has the funds in the account observable, you will receive a payment_settled webhook.

Get access to merchant accounts

Check out how to get access to a merchant account.

When you sign up on console you get access to two merchant accounts on sandbox for EUR and GBP to try out capabilities of our merchant accounts.

Live merchant accounts

To use merchant accounts in your live environment, contact Support. Note that live merchant accounts are real bank accounts.

In sandbox, there is an upper limit of 50000 GBP for withdrawals from a merchant account. This limit does not apply to live merchant accounts.

You can find your merchant account details in your Console or by making requests to our merchant account endpoints.

Payment sources

When a new payment into your merchant account settles successfully, the source of this payment is a new payment_source.

📘

Payment source

Payment sources are accounts from which your merchant account received a payment. Every payment source is a candidate for a payout or a refund, as the source has successfully sent a fund to your merchant account and TrueLayer has settled the transaction.

You can check the payment_source resource field in the Webhooks event Settled. For example:

{
    "event_version": 1,
    "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
    "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
    "settled_at": "2021-12-25T15:00:00.000Z",
    "payment_source": {
        "id": "e2b41c9d-176k-67aa-b2da-fe1a2b97253c",
        "account_identifiers": [
            {
                "type": "sort_code_account_number",
                 "sort_code": "string",
                 "account_number": "string"
            }
        ],
        "account_holder_name": "string"
    }
}

The payment_source field will also appear in the payment resource on GET /payments/{id}, if the payment has settled.

Every payment_source has an id and a type. Currently, the only value available for payment_source.type is external_account. This value represents your user's personal bank account.

You can use the payment_source.id for a payout by making a POST /payouts call as follows:

POST /payouts
{
    "merchant_account_id": "{UUID}",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "payment_source",
        "payment_source_id": "e2b41c9d-176k-67aa-b2da-fe1a2b97253c",
        "user_id": "{UUID}",
        "reference": "string"
    }
}

Did this page help you?