payout / developers
Guide

Webhooks

On this page

Payout sends webhooks as POST requests with a JSON body to the notify URL of your API key. Verify the signature of every webhook as described in Simple payment.

Delivery and retries

A webhook is delivered when your server responds with a 2xx or 3xx status code. Payout doesn't follow redirects.

After any other status code, a timeout or a connection error, Payout sends the webhook again. It makes 5 attempts in total:

Attempt Sent
1 immediately
2 1 minute after the 1st attempt
3 2 minutes after the 2nd attempt
4 3 minutes after the 3rd attempt
5 4 minutes after the 4th attempt

On a timeout or a connection error, Payout repeats each attempt up to 5 more times, 9 to 90 seconds apart, so the next attempt can come later.

If the 5th attempt fails too, Payout stops and notifies your account by e-mail. Contact support to have the webhook sent again.

Tip

Respond within 5 seconds and process the webhook afterwards. The same webhook can arrive more than once, so process it idempotently by external_id and type.

Webhook types

The type is in the type field of the webhook.

Type Sent when
checkout.succeeded The checkout was paid.
checkout.expired The checkout was not paid within the expiration time of your account, 10 days by default. A late bank transfer can still change it to succeeded.
checkout.finalized is_status_final of the checkout changed to true. Available on request.
checkout.verification A bank payment was matched to the checkout. Available on request, see Checkout verification webhook.
checkout.pre_authorized The amount was authorized on the card, see Capture and cancel.
checkout.captured The authorized amount was captured.
checkout.canceled The authorization was cancelled.
checkout.refund_requested A refund of the checkout was requested, see Refund.
payu_token.created The card was stored, see Store card.
payu_token.not_created The card could not be stored.
payu_token.deleted The stored card was deleted.
recurrent.failed A recurrent payment failed, see Recurrent payment.
recurrent.invalid_token The card token of a recurrent payment is invalid.
withdrawal.in_transit The withdrawal was sent to the bank, see Withdrawal.
withdrawal.paid The withdrawal was paid out.
withdrawal.failed The withdrawal failed or was cancelled.
withdrawal.vop_result The Verification of Payee result is known, see M2M Withdrawals.

Was this page helpful?