Payment basics
Learn about the types of payments that you can accept using the Payments API.
There are two types of single payment that end users can make through TrueLayer:
- A closed-loop pay-in, where they make a single payment into your merchant account.
- A single payment, where they pay a beneficiary using the relevant bank details.
This is also known as a 'single domestic payment' or 'single international payment', as defined in the Open Banking Standards.
The payment flow for a closed-loop pay-in vs a single payment. The extra layer between your business account and the user in a merchant account pay-in enables additional functionality.
To create a closed-loop pay-in or single payment request, you send a POST request to the /v3/payments endpoint. Your request should contain a variety of information about the payment, such as its value, whether it's a bank transfer or payment on a mandate, and information about the remitter. Learn more about how to configure your payment requests.
When you create a payment, most of the request is the same for either a merchant account pay-in or a single payment. However, you need to provide a different value for the payment_method.beneficiary.type parameter in your API request.
- For a closed-loop pay-in, use
merchant_account. - For a single payment, use
external_account.
You can still make a single payment into an account that you own.
Info to provide in your request
When you create a payment, you must include the mandatory fields below depending on its type:
| Payment type | Required details |
|---|---|
| Closed-loop pay-in | - The value of the payment - The currency that the payment is in - bank_transfer set as the payment method- A merchant account as the beneficiary, and the associated id- What banks your user can choose to pay from - What schemes your user can choose to pay with - Some user information about the remitter |
| Single payment | - The value of the payment - The currency that the payment is in - bank_transfer set as the payment method- An external account as the beneficiary, with the following details: 1. The name of the external account holder 2. The sort code and account number, IBAN, BBAN or NRB of the external account 3. A reference, which appears on the bank statement of the remitter and beneficiary - What banks your user can choose to pay from, or a single bank id- What payment schemes your user can choose to pay with -Some user information about the remitter |
For a complete guide to payment creation requests, including optional fields to fill out for more functionality, read our Create a payment guide or see the API reference.
Extra features for closed-loop pay-ins
If you choose to receive payments from your users as closed-loop pay-ins, you get access to more features, such as:
- Payment risk and credit notifications, which tell you when you can safely credit a user even if a payment won't settle for some time.
- Payment verification, where a payment is taken through a holding account, and only arrives in your account after the user's age or address are verified.
- Low balance notifications, which tell you when you need to top up your account to ensure you can continue paying your users.
Closed-loop pay-ins enable other TrueLayer products such as refunds, closed-loop payouts, and payment links.
Payment lifecycle
After you authenticate a payment, a payment moves through three stages. These are the same for merchant account pay-ins and single payments.
- Payment creation: Configure your payment and send an API request to create it.
- Authorisation: After the payment is created, the user logs into their bank and authorises the payment being made from their account.
- Payment monitoring: After the payment is authorised, monitor its progress. Payments that succeed move into the states
executedorsettled. Payments that fail move into thefailedstate.
We recommend that you use webhooks to keep track of payments and to get data about why failed payments didn't succeed.
Updated 3 months ago