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",
        "paymentMethodType": "ApplePay",
        "threeDAuthenticated": "false",
        "paymentLinkReference": "78c5ec6ea95477",
        "paymentLinkDescription": "Payment for Custom T-shirt Design",
        "shopperInformation": {
            "ssn": "1111111119",
            "fullName": "Jón Jónsson",
            "emailAddress": ""
        }
    }
}

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",
        "paymentMethodType": "Cards",
        "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.

Straumur Kortalán Authorization

A payment made with Straumur Kortalán has paymentMethod: "KOR". Kortalán is a loan, not a card, so the card fields (cardNumber, cardSummary, cardExpiryDate, threeDAuthenticated and authCode) are not sent, and reason is null. The payfacReference is the Straumur Kortalán reference for the payment. Treat it as an opaque string, since its format differs from card payments.

You only receive an Authorization event for a Straumur Kortalán payment once it has been approved. A shopper who is declined by Kortalán or cancels in the Kortalán application can try again in the same checkout, and no event is sent for that attempt.

{
    "checkoutReference": "9eh9g1loq8ygdmtj1kw47dbogkr2qyijyen53hnglpx2eq4213",
    "payfacReference": "KL-7Q2M9X4T",
    "merchantReference": "89807267361535",
    "amount": "2500000",
    "currency": "ISK",
    "reason": null,
    "success": "true",
    "hmacSignature": "t+URVwf3CYh1K9RopFhXVzVWBI/Z0oSOeojV+frqzG4=",
    "additionalData": {
        "eventType": "Authorization",
        "cardUsage": "Debit",
        "paymentMethod": "KOR",
        "paymentMethodType": "Kortalan"
    }
}

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 successful and refused card 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.

Payment method codes

additionalData.paymentMethod is one of these codes. Apple Pay and Google Pay payments report the brand of the underlying card (for example VI or MC), not a wallet code. The field is left out when the card brand could not be identified. To tell a wallet payment from a plain card payment, use paymentMethodType.

Code	Payment method
VI	Visa
MC	Mastercard
MAE	Maestro
AX	American Express
DIN	Diners Club
DIS	Discover
JCB	JCB
CUP	China UnionPay
AP	Alipay
WCP	WeChat Pay
AUR	Aur
KOR	Straumur Kortalán

Which of these you can receive depends on the payment methods enabled for your store. Handle an unknown code gracefully, since new payment methods may be added.

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. See Payment method codes.
paymentMethodType	nullable string	How the shopper paid: Cards, ApplePay, GooglePay, WeChatPay, AliPay or Kortalan. A wallet payment still reports its card brand in paymentMethod. Omitted when it cannot be determined.
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.
paymentLinkReference	nullable string	A unique identifier for the payment link used to create authorization.
paymentLinkDescription	nullable string	A human-readable description of the payment link.
shopperInformation	nullable object	The shopper's answers to the Payment Link's form. See Shopper Information. Only present for Payment Link payments.

Shopper Information

When a payment comes from a Payment Link, shopperInformation holds the values submitted with the link's form, one property per field:

• A field on the form has the value the shopper entered, or an empty string ("") if they left it empty.
• A prefilled field has the value you set on the link. On Tokenize by Link the shopper cannot change it; on Pay by Link they can edit it, so you get the value they submitted.
• A field that is not on the link's form is left out, like other optional webhook fields.

If the link has no form fields, shopperInformation is left out.

Field	Type	Description	Example
ssn	nullable string	The shopper's kennitala.	1111111119
fullName	nullable string	The shopper's full name.	Jón Jónsson
address	nullable string	Street address.	Laugavegur 1
postCode	nullable string	Postal code.	101
city	nullable string	City.	Reykjavík
country	nullable string	Country.	Iceland
telephone	nullable string	Phone number.	5555555
emailAddress	nullable string	Email address.	""
comments	nullable string	Free-text comments.	Leave at door