Authorization event

This webhook event is triggered when a payment authorization has been processed, and tells you the outcome: success: "true" means funds have been reserved on the customer's payment method, success: "false" means the attempt was refused. The event includes transaction details, payment method information, and authentication status to help you track and manage authorized payments.

Auto-capture and this event

By default, payments are captured immediately. In that case, a successful Authorization event (success: "true") is your fulfilment signal — the funds have already been captured, and no separate Capture event will be sent. You'll only receive a Capture event for payments created with isManualCapture or captureHoursDelay — see Payment Lifecycle.

Webhook Examples

Successful Authorization

{
    "checkoutReference": "9eh9g1loq8ygdmtj1kw47dbogkr2qyijyen53hnglpx2eq4213",
    "payfacReference": "OOJWITWVQV42PSE8",
    "merchantReference": "89807267361535",
    "amount": "100000",
    "currency": "ISK",
    "reason": "383528:1111:03/2030",
    "success": "true",
    "hmacSignature": "V/iaRHNyBnmqVG1mRCZUQo7HTX2sZGgDsJzajV1hOVs=",
    "additionalData": {
        "eventType": "Authorization",
        "authCode": "123456",
        "cardExpiryDate": "03/2030",
        "cardUsage": "Debit",
        "cardNumber": "411111******1111",
        "cardSummary": "1111",
        "paymentMethod": "VI",
        "threeDAuthenticated": "false",
        "paymentLinkIdentifier": "78c5ec6ea95477",
        "paymentLinkDescription": "Payment for Custom T-shirt Design",
    }
}

Refused Authorization

When an authorization is declined, success is "false", reason contains the decline reason instead of card summary data, and authCode is omitted since no authorization code was issued.

{
    "checkoutReference": "9eh9g1loq8ygdmtj1kw47dbogkr2qyijyen53hnglpx2eq4213",
    "payfacReference": "QK3M8ZL2RT9BX1WD",
    "merchantReference": "89807267361535",
    "amount": "100000",
    "currency": "ISK",
    "reason": "Expired Card",
    "success": "false",
    "hmacSignature": "72aiLnDzj4X1SPN1X9uk9pGcYMyO5SlMlzkO7qZf3YY=",
    "additionalData": {
        "eventType": "Authorization",
        "cardExpiryDate": "03/2030",
        "cardUsage": "Debit",
        "cardNumber": "411111******1111",
        "cardSummary": "1111",
        "paymentMethod": "VI",
        "threeDAuthenticated": "false"
    }
}

Common decline reasons

reason is passed through from the card issuer or acquirer, so the exact text can vary. Reasons seen often include Refused, Expired Card, Not enough balance, Blocked Card, Invalid Card Number, CVC Declined, Issuer Unavailable, and Fraud. For e-commerce payments, 3D Not Authenticated is also common — it's reported when the shopper doesn't complete or fails the 3D Secure challenge. Always branch on success, not on the contents of reason.

One checkout, several Authorization events

A decline does not end the checkout session. The shopper can try again with another card or payment method in the same session until the session expires. Each attempt is a separate authorization, so one checkout can send you several Authorization events with success: "false" before either a successful one arrives or the session expires.

All events for the same checkout share the checkoutReference and your merchantReference. Each attempt has its own payfacReference — the two examples above are two attempts in the same checkout.

Sequence 1 — declined, declined, then paid

Step	What happened	Webhook	success	payfacReference	Checkout status
1	Session created	none			New
2	First attempt refused (reason: "Expired Card")	Authorization	false	QK3M8ZL2RT9BX1WD	New
3	Second attempt refused (reason: "CVC Declined")	Authorization	false	HX7N2VPD4KQ8MZ3T	New
4	Third attempt approved	Authorization	true	OOJWITWVQV42PSE8	Completed

Sequence 2 — declined, declined, session expires

Step	What happened	Webhook	success	payfacReference	Checkout status
1	Session created	none			New
2	First attempt refused (reason: "Expired Card")	Authorization	false	QK3M8ZL2RT9BX1WD	New
3	Second attempt refused (reason: "CVC Declined")	Authorization	false	HX7N2VPD4KQ8MZ3T	New
4	Shopper gives up; session reaches expiresAt	none			Expired

How to handle it

• Do not treat the first success: "false" as the end of the order. Keep the order open — the shopper may still pay in the same session.
• For auto-captured payments, fulfil on the first success: "true" for a checkoutReference. For manual or delayed capture, treat it as an authorization only and fulfil after a successful Capture event. Once a checkout is paid, no further Authorization events are sent for it.
• Group events by checkoutReference or merchantReference, not by payfacReference. Store the payfacReference of the successful event — that is the one you pass to capture, refund and the other modifications.
• There is no webhook when a session expires without a payment. If no successful Authorization has arrived by the session's expiresAt (default one hour), call the Checkout Status Request — Expired means the shopper never paid.
• Each event is delivered independently and may be retried, so make your handler idempotent per payfacReference. See Delivery.

Headers

In the Authorization header, we will set the matching Api key for your webhook.

Fields

You will always get these fields.

Field	Type	Description
checkoutReference	nullable string	Unique identifier for the payment that was done through a checkout.
payfacReference	string	Unique identifier for the payment generated by the payment service provider.
merchantReference	nullable string	The identifier for the payment provided by you, the merchant, allowing for correlation with the merchant’s system.
amount	string	The payment amount in the minor currency unit.
currency	string	The three-letter ISO currency code.
reason	nullable string	Additional context about the authorization. On a successful authorization this holds card summary metadata; on a declined authorization it holds the decline reason reported by the card issuer or acquirer (e.g. Expired Card, Not enough balance).
success	string	Indicates the payment status (true/false).
hmacSignature	string	A cryptographic signature generated using a secret, enabling verification of the message authenticity and ensuring it hasn’t been tampered with.
additionalData	object	An object for the additional details included in the event.

Additional Data Fields

Fields you will get depend on the event type of the webhook.

Field	Type	Description
eventType	string	A string representing the type of event that occurred.
authCode	nullable string	An authorization code is a unique series of letters or numbers generated by a card issuer or bank to validate a card payment. Only present on a successful authorization; omitted when the authorization is declined.
cardExpiryDate	nullable string	Card expiration date in "MM/yyyy" format.
cardNumber	nullable string	A partially masked PAN.
cardSummary	nullable string	Last 4 digits of PAN.
cardUsage	nullable string	The source of funds used for a authorization.
paymentMethod	nullable string	The payment method used in the authorization.
threeDAuthenticated	nullable string	Indicates if 3D Secure authentication was completed for this authorization.
untokenizedCardSummary	nullable string	Last 4 digits of original PAN in case of network payment.
paymentLinkIdentifier	nullable string	A unique identifier for the payment link used to create authorization.
paymentLinkDescription	nullable string	A human-readable description of the payment link.