Payment risk and credit notifications

A number of factors can determine the likelihood that a payment will settle in your merchant account and how long it will take to settle. This uncertainty can make it difficult to know when to consider a payment complete and provide services.

You can configure the payment_creditable webhook to find out immediately when you should credit a payment.

A common example of when the payment_creditable webhook can be useful is that payments made over the SEPA Credit Transfer payment scheme 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.

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

Different 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. To enable a different behaviour, contact us.

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

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.

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.

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.

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.

Multiple payment_creditable behaviours with the segment parameter

Usually, a webhook behaviour applies to a country, and payment schemes beneath it. However, you can contact us to define multiple different behaviours 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 their payments always settle as fast as possible, or aren't blocked by your maximum value of outstanding payments.
• You want to ensure the post-settlement behaviour for certain types of transaction. For example, while you confirm a booking is available before you finalise the payment.

To set multiple behaviours for the payment_creditable webhook:

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

Then, if you want to use a specific payment_creditable webhook behaviour for a given payment, pass the name of the segment within the risk_assessment.segment parameter when you create the payment.

📘

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

Risk assessment criteria

Risk assessment affects the payment_creditable webhook for both the risk-assessed and time-bound , whether a payment is considered high- or low-risk is based on several factors. TrueLayer’s risk assessment criteria are based on things such as user behaviours, outstanding payments, and banking providers. You don’t need to provide a user id to benefit from this, as we keep track of users making payments.

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