Webhooks

For notifications, we are the ones contacting you. We call your server to tell it that an event has occurred.

How do we reach you?

Declare your notification URL on your account, and session endings and disputes will be announced there. Alternatively, you can also add a notificationUrl property when creating a session.

Without a notificationUrl at account level or at session level, we will not be able to announce anything.

Four kinds of messages

The event field says which kind of message you are receiving:

event	when
session-ended	a session ended
refund	a refund you asked for has its verdict
debit	a later debit you asked for has its verdict
chargeback	a dispute was opened, sometimes weeks later

session-ended: the end of a session

This is how you learn how a session ended. We call once per session ending with one of these four statuses:

status	what happened
PAID	the order is paid
ABORTED	your customer gave up
EXPIRED	the session reached its time limit
AWAITED_REFUSED	a lender refused the financing

A word on AWAITED_REFUSED

A financing file can leave your customer waiting on the lender’s decision, sometimes for several days.

• If the lender accepts, the session ends PAID and the order is settled by the lender.
• If the lender refuses, the session ends AWAITED_REFUSED and the customer is not charged.

If your customer completes the financing file after the session’s time limit, the session waits for the lender all the same: it ends PAID if the lender accepts, AWAITED_REFUSED if the lender refuses. The ending can then come days after the time limit.

An ending corrected to PAID

Rarely, a session that ended ABORTED or EXPIRED turns out paid: the payment platform took the money after all. Our support checks it and declares the order paid. You then receive a second session-ended message for the same order, with the status PAID and a notificationId of its own. PAID is final: it replaces the earlier ending, and the order is to be fulfilled.

We send you the PSP reference of each operation, the card network a tranche ran on, or the card alias when the order asked to register the means of payment. The extraData you gave when creating the session comes back as given.

{
  "event": "session-ended",
  "notificationId": "019f18f1-cbf4-762f-bd94-776f523c9ffb:PAID",
  "orderId": "EP-123456",
  "extraData": "basket=4412",
  "status": "PAID",
  "total": { "amount": 100000, "currency": "EUR" },
  "captured": { "amount": 100000, "currency": "EUR" },
  "attempts": [
    {
      "attemptId": "019f18f2-6ceb-729c-98b4-d60271a718e0",
      "method": "card",
      "methodId": "card",
      "cardScheme": "visa",
      "cardCode": "497010XXXXXX0007",
      "cardCountry": "FR",
      "provider": "dalenys",
      "status": "CAPTURED",
      "requested": { "amount": 60000, "currency": "EUR" },
      "granted": { "amount": 60000, "currency": "EUR" },
      "operations": [
        {
          "type": "authorization",
          "status": "succeeded",
          "amount": { "amount": 60000, "currency": "EUR" },
          "providerRef": "A180635471",
          "statusCode": "0000",
          "statusMessage": "Successful Operation"
        },
        {
          "type": "capture",
          "status": "succeeded",
          "amount": { "amount": 60000, "currency": "EUR" },
          "providerRef": "A180635474",
          "statusCode": "0000",
          "statusMessage": "Successful Operation"
        }
      ]
    },
    {
      "attemptId": "019f18f3-418c-729c-98b4-e2d7be7c6163",
      "method": "wero",
      "methodId": "wero",
      "provider": "payplug-retail",
      "status": "CAPTURED",
      "requested": { "amount": 40000, "currency": "EUR" },
      "granted": { "amount": 40000, "currency": "EUR" },
      "operations": [
        {
          "type": "payment",
          "status": "succeeded",
          "amount": { "amount": 40000, "currency": "EUR" },
          "providerRef": "pay_6GEUtvaN0NH68vioAWb9LF"
        }
      ]
    }
  ]
}

In this example, a €1,000 order, paid in two tranches: €600 by card, then €400 with Wero. That is a split payment as your server sees it.

provider says which API the tranche’s providerRefs live in, so you know which back-office to open if needed.

How many operations, and of which type, depends on the method and the API, and the example above shows two shapes.

• The card here is an authorization followed by a capture.
• The Wero payment settles in a single payment operation.

cardScheme gives the card’s network: visa, cb, mastercard, amex… On a co-badged card, it is the network the cardholder actually chose.

cardCode gives the card as the PSP masked it: its first six and last four digits, the rest X (497010XXXXXX0007). cardCountry gives the country of the card’s issuer, ISO 3166 alpha-2 (FR). Both come only when the PSP gave them; never a full card number.

bnplPlan gives the financing plan your customer chose, on a financed tranche: { "installments": 3, "withFees": true }.

What we expect of your endpoint

We consider everything went well when you return an HTTP response with status 200 whose body is OK in text/plain. In every other case, we retry at t+1 second, t+1 minute, then t+5 minutes, after which we stop and someone is told.

We fill the authorization header with the value agreed with you. To prevent interception, your endpoint must be https.

refund: a refund

A refund call answers 202 with the refund: succeeded or failed when the PSP decided on the spot, pending when it has not yet. Either way, this message brings you the verdict, once per refund:

{
  "event": "refund",
  "notificationId": "019f18f1-cbf4-762f-bd94-776f523c9ffb:019f2b44-0d1e-7c3a-8e5f-6a7b8c9d0e1f",
  "orderId": "EP-123456",
  "extraData": "avoir-EP-123456-01",
  "sessionId": "019f18f1-cbf4-762f-bd94-776f523c9ffb",
  "attemptId": "019f18f2-6ceb-729c-98b4-d60271a718e0",
  "method": "card",
  "cardScheme": "visa",
  "cardCode": "497010XXXXXX0007",
  "cardCountry": "FR",
  "transactionId": "019f2b44-0d1e-7c3a-8e5f-6a7b8c9d0e1f",
  "status": "succeeded",
  "amount": { "amount": 2500, "currency": "EUR" },
  "provider": "dalenys",
  "providerRef": "A180711904",
  "statusCode": "0000",
  "statusMessage": "Successful Operation"
}

• status: succeeded, the money went back to your customer; failed, nothing was refunded and the amount is refundable again.
• extraData: the tag you gave this refund, echoed as given.
• transactionId: the refund the call answered.
• method and cardScheme: what the money goes back to, as in the session ending: the tranche’s payment method and, for a card, its network. No cardScheme means the PSP named no network we know, not that it was not a card. cardCode and cardCountry too, when the PSP gave them.

debit: a later debit

When you debit a registered card later, the call answers before the money moves. This message brings you the verdict, once per debit:

{
  "event": "debit",
  "notificationId": "019f18f1-cbf4-762f-bd94-776f523c9ffb:019f2a10-5c21-7a8e-9d3f-1b2c3d4e5f60",
  "orderId": "EP-123456",
  "extraData": "retenue-EP-123456-01",
  "sessionId": "019f18f1-cbf4-762f-bd94-776f523c9ffb",
  "attemptId": "019f18f2-6ceb-729c-98b4-d60271a718e0",
  "method": "card",
  "cardScheme": "visa",
  "cardCode": "497010XXXXXX0007",
  "cardCountry": "FR",
  "transactionId": "019f2a10-5c21-7a8e-9d3f-1b2c3d4e5f60",
  "status": "succeeded",
  "amount": { "amount": 8000, "currency": "EUR" },
  "provider": "dalenys",
  "providerRef": "A180702211",
  "statusCode": "0000",
  "statusMessage": "Successful Operation"
}

• status: succeeded, the money was taken; failed, nothing was debited and the amount no longer counts against maximumFutureDebit.
• extraData: the tag you gave this debit, echoed as given.
• transactionId: the debit the call answered.
• method and cardScheme: the registered card’s method and, when the PSP named it, its network, its masked number and its country, as in the session ending.

Tell your customer: we do not contact them. The delivery follows the same rules as a session ending.

Disputes (chargebacks)

A chargeback happens when the cardholder’s bank takes the money back, sometimes weeks after the payment. We receive the dispute and relay it to you as it stands: nothing is handled automatically on our side.

{
  "event": "chargeback",
  "notificationId": "A180635474:chargeback:2026-08-18:60000",
  "orderId": "EP-123456",
  "sessionId": "019f18f1-cbf4-762f-bd94-776f523c9ffb",
  "attemptId": "019f18f2-6ceb-729c-98b4-d60271a718e0",
  "transactionId": "019f18f2-73ee-729c-98b4-dd336f0beb22",
  "type": "chargeback",
  "amount": { "amount": 60000, "currency": "EUR" },
  "provider": "dalenys",
  "providerRef": "A180635474",
  "reasonCode": "13.1",
  "status": "First chargeback",
  "date": "2026-08-18",
  "validUntil": "2026-09-15"
}

type says which way the money went.

• chargeback is a debit: a dispute was opened and the money left your account.
• representment is a credit: the dispute was settled in your favour and the money comes back to your account.

validUntil is a deadline. Past that date, the dispute is lost by default. That is why this delivery follows the same rules as a session ending: OK on 200, retries at t+1 s, t+1 min, t+5 min, and why someone is told if we cannot reach you.