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 account 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.](https://files.readme.io/2b1cccb-Closed-loop-pay-in-and-single-payment.png)
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 /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
executed
orsettled
. Payments that fail move into thefailed
state.
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