Payment risk and credit notifications

The payment_creditable webhook tells you when it's an acceptable risk to consider a payment complete.

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 can assess 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

There are a variety of different behaviours you can configure for the payment_creditable webhook. To enable them, contact us so we can change them for your client_id. Here we examine four behaviours you can use:

Status-based notifications

This is the default behaviour for the payment_creditable webhook when enabled.

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.

Enable and configure the payment_creditable webhook

To enable this feature, contact us and specify how you want the webhook to work. You need to provide:

  • A choice from the different behaviours listed above. You need to provide a different behaviour for each payment scheme. These schemes are:
    • Faster Payments Scheme
    • SEPA Instant Credit Transfer
    • SEPA Credit Transfer.
  • Your desired behaviours for TrueLayer’s risk assessment:
    • If you select the risk-assessed behaviour for a scheme, you must specify the countries you want it to apply within.
    • If you select the risk-assessed or time-bound behaviours for a scheme, you must specify a maximum value of low-risk payments outstanding that aren't settled.
      This can be a rolling monthly value or a one-off value, to limit your potential loss to a set threshold.

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"