Merchant accounts

Learn about using merchant accounts to receive and make payments with our 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.

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.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.

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",
        "details": {
            "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"
    }
}

Payout scenarios

Payouts represents money leaving your merchant account into a beneficiary of your choice. Unlike payins via bank_transfer payment method, this action does not require extra authorisation by any user.

Payout to a user

When one of your users requests to withdraw funds back to their account, you can facilitate this exchange by executing payouts from your merchant-account via /payouts resource.

You can call `POST /payouts` to initiate a payment with a beneficiary type `payment_source_external_account` if your user has made a payment into your `merchant account` before. You can view payment sources of a user on a merchant account via calling `GET /merchant-accounts/{id}/payment-sources?user_id={user_id}`You can call `POST /payouts` to initiate a payment with a beneficiary type `payment_source_external_account` if your user has made a payment into your `merchant account` before. You can view payment sources of a user on a merchant account via calling `GET /merchant-accounts/{id}/payment-sources?user_id={user_id}`

You can call POST /payouts to initiate a payment with a beneficiary type payment_source_external_account if your user has made a payment into your merchant account before. You can view payment sources of a user on a merchant account via calling GET /merchant-accounts/{id}/payment-sources?user_id={user_id}

You can facilitate a payout to a user via a call to POST /payouts

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"
    }
}

Payout to your own account

You can also make payouts to your own bank account by using the beneficiary type external_account with relevant details.

POST /payouts
{
    "merchant_account_id": "string",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "external_account",
        "account_holder_name": "string",
        "account_identifier": {
            "type": "sort_code_account_number",
            "sort_code": "00-00-00",
                         "account_number": "12345678",
        },
        "reference": "string"
    }
}

Payout to a Business Account

You can make payouts to your business bank account that you've specified during your onboarding process with TrueLayer with beneficiary type business_account and the relevant details.

POST /payouts
{
    "merchant_account_id": "string",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
                 "type": "business_account",
                 "reference": "string"
         }
}

Did this page help you?