Settlement risk and the payment_creditable webhook

Payments can take several days to settle in your account, such as when they're made over the SEPA Credit scheme in Europe. However, sometimes the chance of these payments settling is very high. You can use credit notifications to tell you when a payment is likely to settle, and then credit your user or provider services before payment settlement. This can greatly improve your user experience.

Credit notifications have a variety of possible behaviours you can choose from. This means that they're a flexible way to reduce your risk which works for a variety of use cases.

As such, we recommend that you use the payment_creditable webhook in all integrations to tell you when a payment into your merchant account should be considered complete. By default, you receive this webhook when a payment settles, but you can contact us to customise the behaviour.

This webhook assesses whether the risk of a payment settling is high or low. If the risk is low and within your risk appetite, you can make the payment sooner and improve your customers' experience.

How can I use the payment_creditable webhook?

The payment_creditable webhook is enabled by default in all new integrations. If you don't have this feature enabled (for example, if you have been using age-verified payments, we strongly recommend that you contact us to turn this feature on.

Payments in Europe

The most common usage of the payment_creditable webhook is to provide a quicker payments experience in Europe. Payments in Europe are often made over the SEPA Credit Transfer payment scheme, which can take up to 3 days to settle. Waiting until the payment has settled before providing your customer with services is a far worse user experience.

By using the risk-assessed behaviour of the payment_creditable webhook, you can ensure that the majority of your users are paid when a payment enters executed status rather than settled, which can take several days. TrueLayer's risk assessment ensures that payments that are high risk are only treated as creditable once they settle, and enables you to speed up payments for your other users.

Different use cases

Some use cases are better suited to the different webhook behaviours explained below. For example:

• The risk-assessed behaviour is very well suited for payments in Europe, over the SEPA Credit scheme.
  You can additionally define segments if you want to ensure that certain payments, such as VIP payments, are excluded from the risk assessment.
• The time-bound behaviour is ideal for ecommerce use cases such as delivery or booking services, where you need time to confirm a service before you accept a payment.
• The post-settlement behaviour is useful if you are very risk averse and want to ensure that you have definitely received money before providing any services.

Different payment_creditable webhook behaviours

Here are the different behaviours you can configure for the payment_creditable webhook. By default, the webhook will notify you based on payment status, and return a payment_creditable webhook at the same time as the settled status. To enable a different behaviour, contact us.

• Status-based notifications
• Risk-assessed notifications
• Time-bound notifications
• Post-settlement notifications

📘

You can't cancel payments after they reach this status

You cannot use the /v3/payments/{id}/actions/cancel endpoint to cancel payments after you receive thepayment_creditable webhook. Instead, you receive a 400 error. This is true even if a payment has not yet settled.

Status-based notifications

This is the default behaviour for the payment_creditable webhook.

You can choose to receive the payment_creditable webhook when a payment reaches a certain status. Typically, this would be settled, but you could also choose executed (this is higher risk, as not all executed payments settle).

Risk-assessed notifications

With risk-assessed notifications, a TrueLayer risk assessment determines the status at which you receive a payment_creditable webhook:

• Low-risk payments are creditable when they have a status of executed.
• High-risk payments are creditable when they have a status of settled.

TrueLayer’s risk assessment criteria are based on things such as payment value, user behaviours, outstanding payments, and banking providers. When you contact us to enable this status, we will confirm the parameters of the risk assessment with you. Risk assessment is applied based on payment details, not a user id.

Time-bound notifications

Time-bound notifications are suitable for integrations where you need to make a decision on a payment quickly (for example, if you are offering time-sensitive services). You specify a duration within which a payment must succeed or fail. This duration begins after a payment reaches authorized status.

With this behaviour, there are two situations where you receive the payment_creditable webhook:

• If the payment reaches the settled status within the duration you specified.
• The duration you specified passes, the payment hasn’t settled, and a TrueLayer risk assessment considers the payment low_risk.

TrueLayer’s risk assessment criteria are based on things such as user behaviours, outstanding payments, and banking providers. Risk assessment is applied based on payment details, not a user id.

Post-settlement notifications

Post-settlement notifications are an option if you have a very low risk appetite. Here, you can postpone when you receive the payment_creditable webhook until after some time has passed since a payment has settled. This can reduce the chance of you crediting a payment before a reversal happens.

📘

If you accept payments in the UK, the time difference between executed, settled and creditable webhooks may be very small. Be aware that you may receive these webhooks out of order, eg settled before executed.

Value-based notifications

You can also configure post-settlement notifications to only apply to transactions above a specified value. You can choose what this value is by contacting us.

For example, you might only add the post settlement delay for payments above £500 in value. This means that high-value payments are much less likely to be reversed after you receive a creditable webhook, but the instant experience is not lost for lower-value payments.

This is also compatible with any existing risk assessment behaviour that you’ve configured.

• If the payment is your specified value or above, we send a creditable webhook a configurable number of seconds after the payment settles.
• If the payment value is below your specified value, we send a creditable notification as we normally would (for example, receiving a status-based notification).

Configure the payment_creditable webhook

The payment_creditable webhook is enabled by default, and you receive it when a payment settles. However, you can contact us to disable this webhook, or to change its behaviours to one of those explained above.

You can specify a different behaviour for the payment_creditable webhook for each country. Alternatively, you can specify multiple for a single country with the segment parameter. To specify your desired behaviour, contact us with the following information:

1. The country you want to apply a new payment_creditable webhook behaviour for.
2. The payment schemes within the country you want the behaviour to apply to. The available options are:
   • Faster Payments Scheme
   • SEPA Instant Credit Transfer
   • SEPA Credit Transfer.
3. If you select the risk-assessed or time-bound behaviour for a country and scheme, you must specify a maximum value of not yet settled low-risk payments. You can specify this as:
   • A rolling monthly basis, where a set value of payments are considered creditable based on risk, after which they're only considered creditable after they settle.
   • A one-off value, where you state a maximum amount of payments to consider creditable based on risk, after which they're only considered creditable after they settle.

Use the segment parameter to change risk assessment for individual payments

By default, if you use the risk-assessed payment_creditable behaviour, it applies to a country and payment schemes beneath it. You also confirm the parameters of the risk assessment with us. However, you can contact us to define different risk assessment parameters for a given country and scheme. These are each known as a segment.

This can be useful in several scenarios. For example:

• You have VIP customers and want to ensure these users are most likely to receive an instant payment experience.
• You sell multiple products with varying AOVs and want to align your risk assessment with the product category.

To set multiple behaviours for the payment_creditable webhook:

1. Contact us and specify the default risk assessment for payment schemes in a country, and a name for the segment.
   It's essential to specify a default. This is what's used when you omit the risk_assessment.segment parameter from a payment.
2. Specify further risk assessment behaviours for payment schemes in that country, with extra names for each segment.

Then, if you want to use a specific risk assessment behaviour for a given payment, pass the name of the segment within the risk_assessment.segment parameter when you create the payment. You then receive the payment_creditable webhook at the appropriate time based on the segment you defined.

📘

As when setting any default payment risk behaviour, you have to contact us to specify each segment for extra behaviours.

Example of credit notifications

An online gaming company has integrated the Payments API v3 with their app. Their customers make payments in the app to top up their balance, which they then use to play games or access other services. They have a large customer base in Europe, which largely pay using SEPA Credit Transfer to avoid any fees when they top up their account.

Over time, the company gets feedback from a number of customers, which are frustrated that it can take 3 working days to access their funds. In order to improve this experience, the company enables the payment_creditable webhook.

They now receive a webhook that enables them to fund the customer account immediately if the:

• The customer has a history of valid payments.
• The customer doesn't have too many other pending payments.
• The payment is from a reliable banking provider.

This is an example of the information returned in the webhook:

{
  "type": "payment_creditable",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "creditable_at": "2023-06-13T15:00:00.000Z"
}