Webhooks

Webhooks (or HTTP callbacks) allow you to subscribe to different events that affect a payment and to be notified directly when these events happen. When an event occurs in Checkout, for example, a charge is made or a payment is refunded, this event can be sent along with the associated data.

In order to receive notification, you first need to subscribe to the events you want to track.

Webhooks related to payments are configured per payment and can be specified in the request body of the following methods:

Create payment using the notifications property.
Charge subscription using the notifications property.

Webhooks related to onboardings are configured per onboarding application and can be specified in the request body of the following methods:

Create onboarding application using the notifications property.
Update onboarding application using the notifications property.

Checkout sends the event as a POST request to the URL you specify. The URL need to be a secure (HTTPS) endpoint.

Expected Response

To acknowledge the webhook sent from Checkout, a 200 HTTP status code is required. Any other status code, even other 2XX codes, will be treated as an unsuccessful attempt. The response cannot take more than 10 seconds, otherwise it will be counted as an unsuccessful attempt.

If the webhook was not successfully posted to you, it will fall under the Retry mechanism described below.

At-Least-Once Delivery

One of the core tenets of webhooks is the concept of at-least-once delivery. This approach ensures that messages are always delivered. It also means that messages can be received more than once, even repeatedly and out of order. For this reason, it's important that the webhook receiver supports the idempotent consumer pattern.

Working under the assumption of at-least-once delivery, especially within the context of an event-driven architecture, is a responsible approach for reliably processing events. Your function must be idempotent so that the outcome of processing the same event multiple times is the same as processing it once.

Retries

An application that communicates with distributed elements has to be sensitive to the transient faults that can occur in this environment. Faults include the momentary loss of network connectivity to components and services, the temporary unavailability of a service, or timeouts that occur when a service is busy.

If the fault is caused by one of the more commonplace connectivity or busy failures, the network or service might need a short period while the connectivity issues are corrected or the backlog of work is cleared. In this case, we will retry for a maximum of 10 times with the following delay intervals: 2, 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90, 120, 250 minutes.

If your site still has not responded successfully after this period, the webhook will not be attempted any more.

Circuit Breaker

In a distributed environment, calls to remote resources and services can fail due to transient faults, such as slow network connections, timeouts, or the resources being overcommitted or temporarily unavailable. These faults typically correct themselves after a short period of time and are handled by a Retry routine.

However, there can also be situations where faults are due to unanticipated events, and that might take much longer to fix. In these situations, it might be pointless for an application to continually retry an operation that is unlikely to succeed. Instead, the application should quickly accept that the operation has failed and handle this failure accordingly.

We will stop sending notifications once more than 20% of webhooks sent to a given endpoint fail within a 30-second timespan. We will then start probing after another 30 seconds to see if the endpoint is healthy again. All not sent notifications during the period when the circuit is open are subject to the Retry routine.

Payment events

The following table lists all payment events that can be subscribed to using the Payment API:

Event name	Description
`payment.created`	A payment has been created.
`payment.reservation.created`	The amount of the payment has been reserved.
`payment.reservation.created.v2`	The amount of the payment has been reserved.
`payment.reservation.failed`	A reservation attempt has failed.
`payment.checkout.completed`	The customer has completed the checkout.
`payment.charge.created.v2`	The customer has successfully been charged, partially or fully.
`payment.charge.failed`	A charge attempt has failed.
`payment.refund.initiated.v2`	A refund has been initiated.
`payment.refund.failed`	A refund attempt has failed.
`payment.refund.completed`	A refund has successfully been completed.
`payment.cancel.created`	A reservation has been canceled.
`payment.cancel.failed`	A cancellation has failed.

Created

The payment.created event is triggered when a new payment is created. This happens when the customer hits the "Pay" button on the checkout page.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.created.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- orderobjectrequired
  The complete order associated with the payment.
  - amountobjectrequired
    The amount of the charge.
    amountinteger (int32)required
    The amount, for example 10000.
    currencystringrequired
    The currency, for example 'SEK'.
  - referencestringrequired
    A reference to recognize this order. Usually a number sequence (order number).
  - orderItemsarrayrequired
    The list of order items that are associated with the failed charge. Contains at least one order item.
    referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
    namestringrequired
    The name of the product.
    quantitynumber (double)required
    The quantity of the product.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
    unitPriceinteger (int32)required
    The price per unit excluding VAT.
    taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).

Example

payment.created

{
    "id": "458a4e068f454f768a40b9e576914820",
    "merchantId": 100017120,
    "timestamp": "2021-05-04T22:08:16.6623+02:00",
    "event": "payment.created",
    "data": {
        "order": {
            "amount": {
                "amount": 5500,
                "currency": "SEK"
            },
            "reference": "42369",
            "orderItems": [
                {
                    "reference": "Sneaky NE2816-82",
                    "name": "Sneaky",
                    "quantity": 2,
                    "unit": "pcs",
                    "unitPrice": 2500,
                    "taxRate": 1000,
                    "taxAmount": 500,
                    "netTotalAmount": 5000,
                    "grossTotalAmount": 5500
                }
            ]
        },
        "paymentId": "02a900006091a9a96937598058c4e474"
    }
}

Reservation created

Please note that there are two versions of the payment.reservation.created. The payment.reservation.created.v2 is triggered when the amount of the payment has been reserved.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.reservation.created.v2.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- orderobjectrequired
  The complete order associated with the payment.
  - amountobjectrequired
    The amount of the charge.
    amountinteger (int32)required
    The amount, for example 10000.
    currencystringrequired
    The currency, for example 'SEK'.
  - referencestringrequired
    A reference to recognize this order. Usually a number sequence (order number).
  - orderItemsarrayrequired
    The list of order items that are associated with the failed charge. Contains at least one order item.
    referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
    namestringrequired
    The name of the product.
    quantitynumber (double)required
    The quantity of the product.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
    unitPriceinteger (int32)required
    The price per unit excluding VAT.
    taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).

Example

payment.reservation.created

{
    "id": "6f081ae39b9846c4bacff88fa2cecc98",
    "merchantId": 100001234,
    "timestamp": "2022-09-21T09:50:05.9440+00:00",
    "event": "payment.reservation.created",
    "data": {
        "cardDetails": {
            "creditDebitIndicator": "D",
            "expiryMonth": 1,
            "expiryYear": 24,
            "issuerCountry": "NO",
            "truncatedPan": "492500******0004",
            "threeDSecure": {
                "authenticationEnrollmentStatus": "Y",
                "authenticationStatus": "Y",
                "eci": "05"
            }
        },
        "paymentMethod": "Visa",
        "paymentType": "CARD",
        "consumer": {
            "ip": "10.230.197.32"
        },
        "reservationReference": "683884",
        "reserveId": "6f081ae39b9846c4bacff88fa2cecc98",
        "amount": {
            "amount": 1000,
            "currency": "SEK"
        },
        "paymentId": "01d40000632ade184172b85d8cc3f516"
    }
}

Example v2

payment.reservation.created.v2

{
    "id": "c25459e92ba54be1925493f987fb05a7",
    "timestamp": "2021-05-04T22:09:08.4342+02:00",
    "merchantNumber": 100017120,
    "event": "payment.reservation.created.v2",
    "data": {
        "paymentMethod": "Visa",
        "paymentType": "CARD",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "02a900006091a9a96937598058c4e474"
    }
}

Reservation failed

The payment.reservation.failed event is triggered when a reservation fails. The main use case are bulk charge subscriptions. Another use case could be to get informed about failed subscription or unscheduled charge attempts.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.created.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- amountobjectoptional
  The amount of the charge.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.
orderItemsarrayoptional
The list of order items that are associated with the failed reservation and charge. Contains at least one order item.
- referencestringoptional
  A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
- namestringoptional
  The name of the product.
- quantitynumber (double)optional
  The quantity of the product.
- unitstringoptional
  The defined unit of measurement for the product, for example pcs, liters, or kg.
- unitPriceinteger (int32)optional
  The price per unit excluding VAT.
- taxRateinteger (int32)optional
  The tax rate. Defaults to 0 if not provided.
- taxAmountinteger (int32)optional
  The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
- grossTotalAmountinteger (int32)optional
  The total amount including VAT (netTotalAmount + taxAmount).
- netTotalAmountinteger (int32)optional
  The total amount excluding VAT (unitPrice * quantity).

Example

reservation.failed

{
  "id": "ef0f698086ac4e7493439ab4290695da",
  "merchantId": 100008172,
  "timestamp": "2022-06-30T10:54:07.7765+02:00",
  "event": "payment.reservation.failed",
  "data": {
    "error": {
      "code": "33",
      "message": "Direct charge failed for payment id: 020b000062bd64ae0a5e7c95f6055f66. ErrorMessage: Refused by issuer",
      "source": "Issuer"
    },
    "orderItems": [
      {
        "grossTotalAmount": 133,
        "name": "NameBulkCharge1",
        "netTotalAmount": 133,
        "quantity": 1,
        "reference": "bulk123",
        "taxRate": 0,
        "taxAmount": 0,
        "unit": "quantity",
        "unitPrice": 133
      }
    ],
    "amount": {
      "amount": 133,
      "currency": "DKK"
    },
    "paymentId": "020b000062bd64ae0a5e7c95f6055f66"
  }
}

Checkout completed

The payment.checkout.completed event is triggered when the customer has completed the checkout.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.checkout.completed.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- orderobjectrequired
  Specifies the order associated with the payment.
  - amountobjectrequired
    The total amount of the order including VAT, if any.
    amountinteger (int32)required
    The total amount of the order, for examlpe 10000.
    currencystringrequired
    The currency of the payment, for example 'SEK'.
  - referencestringrequired
    A reference to recognize this order. Usually a number sequence (order number).
  - orderItemsarrayrequired
    An array of order items. Contains at least one item.
    referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
    namestringrequired
    The name of the product.
    quantitynumber (double)required
    The quantity of the product.
    unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
    unitPriceinteger (int32)required
    The price per unit excluding VAT.
    taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
    taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
    grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
    netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).

Example

payment.checkout.completed

{
    "id": "36ce3ff4a896450ea2b70f3263554772",
    "merchantId": 100017120,
    "timestamp": "2021-05-04T22:09:08.4342+02:00",
    "event": "payment.checkout.completed",
    "data": {
        "order": {
            "amount": {
                "amount": 5500,
                "currency": "SEK"
            },
            "reference": "Hosted Demo Order",
            "orderItems": [
                {
                    "reference": "Sneaky NE2816-82",
                    "name": "Sneaky",
                    "quantity": 2,
                    "unit": "pcs",
                    "unitPrice": 2500,
                    "taxRate": 1000,
                    "taxAmount": 500,
                    "netTotalAmount": 5000,
                    "grossTotalAmount": 5500
                }
            ]
        },
        "consumer": {
            "firstName": "John",
            "lastName": "Doe",
            "billingAddress": {
                "addressLine1": "Solgatan 4",
                "addressLine2": "",
                "city": "STOCKHOLM",
                "country": "SWE",
                "postcode": "11522",
                "receiverLine": "John doe"
            },
            "country": "SWE",
            "email": "john.doe@example.com",
            "ip": "192.230.114.3",
            "phoneNumber": {
                "prefix": "+46",
                "number": "12345678"
            },
            "shippingAddress": {
                "addressLine1": "Solgatan 4",
                "addressLine2": "",
                "city": "STOCKHOLM",
                "country": "SWE",
                "postcode": "11522",
                "receiverLine": "John Doe"
            }
        },
        "paymentId": "02a900006091a9a96937598058c4e474"
    }
}

Cancel created

The payment.cancel.created event is triggered when a reservation has been canceled.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.cancel.created.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- cancelIdstringrequired
- orderItemsarrayrequired
  The list of order items that are associated with the canceled payment. Contains at least one order item.
  - referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
  - namestringrequired
    The name of the product.
  - quantitynumber (double)required
    The quantity of the product.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
  - unitPriceinteger (int32)required
    The price per unit excluding VAT.
  - taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).
- amountobjectrequired
  The amount of the charge.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.cancel.created

{
    "id": "df7f9346097842bdb90c869b5c9ccfa9",
    "merchantId": 100017120,
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "payment.cancel.created",
    "data": {
        "cancelId": "df7f9346097842bdb90c869b5c9ccfa9",
        "orderItems": [
            {
                "reference": "Sneaky NE2816-82",
                "name": "Sneaky",
                "quantity": 2,
                "unit": "pcs",
                "unitPrice": 2500,
                "taxRate": 1000,
                "taxAmount": 500,
                "netTotalAmount": 5000,
                "grossTotalAmount": 5500
            }
        ],
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "006400006091abfe6937598058c4e47e"
    }
}

Cancel failed

The payment.cancel.failed event is triggered when a cancellation of a reservation has failed.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.cancel.failed.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- errorobjectrequired
  Contains information about an error (client error or server error).
  - messagestringoptional
    An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.
  - codestringoptional
    A numeric error code to be used for debugging purposes.
  - sourcestringoptional
    The source of the error, for example: 'internal'.
- cancelIdstringrequired
- orderItemsarrayrequired
  The list of order items that are associated with the failed charge. Contains at least one order item.
  - referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
  - namestringrequired
    The name of the product.
  - quantitynumber (double)required
    The quantity of the product.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
  - unitPriceinteger (int32)required
    The price per unit excluding VAT.
  - taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).
- amountobjectrequired
  The amount of the charge.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.cancel.failed

{
    "id": "df7f9346097842bdb90c869b5c9ccfa9",
    "merchantId": 100017120,
    "timestamp": "2021-05-06T11:37:30.1114+02:00",
    "event": "payment.cancel.failed",
    "data": {
        "error": {
            "code": "25",
            "message": "Trans not found",
            "source": "Internal"
        },
        "cancelId": "df7f9346097842bdb90c869b5c9ccfa9",
        "orderItems": [
            {
                "reference": "Sneaky NE2816-82",
                "name": "Sneaky",
                "quantity": 2,
                "unit": "pcs",
                "unitPrice": 2500,
                "taxRate": 1000,
                "taxAmount": 500,
                "netTotalAmount": 5000,
                "grossTotalAmount": 5500
            }
        ],
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "023a00005ea744ed368812223c86c299"
    }
}

Charge created

The payment.charge.created.v2 event is triggered when the customer has successfully been charged, partially or fully. A use case can be to get notified for successful subscription or unscheduled charges.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantNumberintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.charge.created.v2.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- subscriptionIdstringoptional
  The subscription identifier.
- chargeIdstringrequired
  The charge identifier.
- orderItemsarrayrequired
  The list of order items that are associated with the charge. Contains at least one order item.
  - referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
  - namestringrequired
    The name of the product.
  - quantitynumber (double)required
    The quantity of the product.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
  - unitPriceinteger (int32)required
    The price per unit excluding VAT.
  - taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).
- paymentMethodstringrequired
  The payment method, for example 'Visa' or 'Mastercard'.
- paymentTypestringrequired
  The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.
- amountobjectrequired
  The amount of the charge.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.charge.created.v2

{
    "id": "01ee00006091b2196937598058c4e488",
    "timestamp": "2021-05-04T22:44:10.1185+02:00",
    "merchantNumber": 100017120,
    "event": "payment.charge.created.v2",
    "data": {
        "chargeId": "01ee00006091b2196937598058c4e488",
        "orderItems": [
            {
                "reference": "Sneaky NE2816-82",
                "name": "Sneaky",
                "quantity": 2,
                "unit": "pcs",
                "unitPrice": 2500,
                "taxRate": 1000,
                "taxAmount": 500,
                "netTotalAmount": 5000,
                "grossTotalAmount": 5500
            }
        ],
        "paymentMethod": "Visa",
        "paymentType": "CARD",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "025400006091b1ef6937598058c4e487"
    }
}

Charge failed

The payment.charge.failed event is triggered when a charge attempt has failed.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.charge.failed.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- errorobjectrequired
  Contains information about an error (client error or server error).
  - messagestringoptional
    An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.
  - codestringoptional
    A numeric error code to be used for debugging purposes.
  - sourcestringoptional
    The source of the error, for example: 'internal'.
- chargeIdstringrequired
  The charge identifier.
- orderItemsarrayrequired
  The list of order items that are associated with the failed charge. Contains at least one order item.
  - referencestringrequired
    A reference to recognize the product, usually the SKU (stock keeping unit) of the product. For convenience in the case of refunds or modifications of placed orders, the reference should be unique for each variation of a product item (size, color, etc.)
  - namestringrequired
    The name of the product.
  - quantitynumber (double)required
    The quantity of the product.
  - unitstringrequired
    The defined unit of measurement for the product, for example pcs, liters, or kg.
  - unitPriceinteger (int32)required
    The price per unit excluding VAT.
  - taxRateinteger (int32)optional
    The tax rate. Defaults to 0 if not provided.
  - taxAmountinteger (int32)optional
    The tax/VAT amount. Defaults to 0 if not provided. taxAmount should include the total tax amount for the entire order item.
  - grossTotalAmountinteger (int32)required
    The total amount including VAT (netTotalAmount + taxAmount).
  - netTotalAmountinteger (int32)required
    The total amount excluding VAT (unitPrice * quantity).
- reservationIdstring (uuid)required
  A unique identifier (UUID) for the reservation that can help in diagnostics.
- amountobjectrequired
  The amount of the charge.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.charge.failed

{
    "id": "02a8000060923bcb6937598058c4e77a",
    "merchantId": 100017120,
    "timestamp": "2021-05-05T08:31:39.2481+02:00",
    "event": "payment.charge.failed",
    "data": {
        "error": {
            "code": "99",
            "message": "Auth Fin Failure",
            "source": "Internal"
        },
        "chargeId": "02a8000060923bcb6937598058c4e77a",
        "orderItems": [
            {
                "reference": "Sneaky NE2816-82",
                "name": "Sneaky",
                "quantity": 2,
                "unit": "pcs",
                "unitPrice": 2500,
                "taxRate": 1000,
                "taxAmount": 500,
                "netTotalAmount": 5000,
                "grossTotalAmount": 5500
            }
        ],
        "reservationId": "0527cb1dc5d14491824644a84d5ccf69",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "029b000060923a766937598058c4e6fa"
    }
}

Refund initiated

The payment.refund.initiated event is triggered when a refund has been initiated.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantNumberintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.refund.initiated.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier
- refundIdstringrequired
  A unique identifier of this refund.
- chargeIdstringrequired
  The charge identifier.
- amountobjectrequired
  The amount of the refund.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.refund.initiated

{
    "id": "00fb000060923e006937598058c4e7f3",
    "timestamp": "2021-05-05T08:41:04.6081+02:00",
    "merchantNumber": 100017120,
    "event": "payment.refund.initiated",
    "data": {
        "refundId": "00fb000060923e006937598058c4e7f3",
        "chargeId": "0107000060923dde6937598058c4e7ee",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "012b000060923cf26937598058c4e7e6"
    }
}

Refund completed

The payment.refund.completed event is triggered when a refund has successfully been completed.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.refund.completed.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier
- refundIdstringrequired
  A unique identifier of this refund.
- amountobjectrequired
  The amount of the refund.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.
- invoiceDetailsobjectoptional
  - distributionTypestringrequired
    The type of distribution, for example 'Email'.
  - invoiceDueDatestringrequired
    The due date of the invoice.
  - invoiceNumberstringrequired
    The invoice number.

Example

payment.refund.completed

{
    "id": "458a4e068f454f768a40b9e576914820",
    "merchantId": 100017120,
    "timestamp": "2021-05-04T22:08:16.6623+02:00",
    "event": "payment.refund.completed",
    "data": {
        "refundId": "00fb000060923e006937598058c4e7f3",
        "invoiceDetails":{
            "distributionType": "Email",
            "invoiceDueDate": "2021-01-01T00:00:00",
            "invoiceNumber": "800328091K1"
        },
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "012b000060923cf26937598058c4e7e6"
    }
}

Refund failed

The payment.refund.failed event is triggered when a refund attempt has failed.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.refund.failed.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier
- refundIdstringrequired
  A unique identifier of this refund.
- errorobjectrequired
  Contains information about an error (client error or server error).
  - messagestringoptional
    An internal error message. This message is not meant to be presented to the customer. Instead, this message can be logged and used for debugging purposes.
  - codestringoptional
    A numeric error code to be used for debugging purposes.
  - sourcestringoptional
    The source of the error, for example: 'internal'.
- amountobjectrequired
  The amount of the refund.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.
- invoiceDetailsobjectoptional
  - distributionTypestringrequired
    The type of distribution, for example 'Email'.
  - invoiceDueDatestringrequired
    The due date of the invoice.
  - invoiceNumberstringrequired
    The invoice number.

Example

payment.refund.failed

{
    "id": "458a4e068f454f768a40b9e576914820",
    "merchantId": 100017120,
    "timestamp": "2021-05-04T22:08:16.6623+02:00",
    "event": "payment.refund.failed",
    "data": {
        "error": {
            "code": "25",
            "message": "Some error message",
            "source": "Internal"
        },
        "refundId": "00fb000060923e006937598058c4e7f3",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "012b000060923cf26937598058c4e7e6"
    }
}

Onboarding events

The following table lists all events that can be subscribed to using the Boarding API:

Event name	Description
`onboarding.initiated`	The onboarding application has been initiated and can be edited and submitted.
`onboarding.awating_signature`	The onboarding application has been submitted and is in the signing process.
`onboarding.signature_failed`	The signing process failed for one or more reasons.
`onboarding.processing`	The onboarding application has been signed by the merchant and is in the review process.
`onboarding.approved`	The onboarding application has been approved.
`onboarding.abandoned`	The onboarding application has been abandoned, either because signing failed or an application was rejected.

Initiated

The onboarding.initiated event is triggered when an onboarding application has been initiated. After this event has triggered, the application can be edited and submitted.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.initated.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.initiated

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "merchantNumber": 12345,
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.initated",
    "data": {
        "onboardingId": 6259,
        "status": "INITIATED"
    }
}

Awaiting signature

The onboarding.awaiting_signature event is triggered when an onboarding application has been submitted and is in the signing process.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.awaiting_signature.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.awating_signatur

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.awaiting_signature",
    "data": {
        "onboardingId": 6259,
        "status": "AWAITING_SIGNATURE"
    }
}

Signature failed

The onboarding.signature_failed event is triggered when the signing process failed for or many reasons. See the property data.reason below.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at whitch the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.signature_failed.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process, in this case 'SIGNATURE_FAILED'.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.signature_failed

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-05T11:33:33.5969Z",
    "event": "onboarding.SIGNATURE_FAILED",
    "data": {
        "onboardingId": 6259,
        "status": "SIGNATURE_FAILED",
        "reason": "expired"
    }
}

Processing

The onboarding.processing event is triggered when an onboarding application has been signed by the merchant and is in the review process.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.processing.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process, in this case 'PROCESSING'.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.processing

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.processing",
    "data": {
        "onboardingId": 6259,
        "status": "PROCESSING"
    }
}

Approved

The onboarding.approved event is triggered when an onboarding application has been approved.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.approved.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.approved

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.approved",
    "data": {
        "onboardingId": 6259,
        "status": "APPROVED"
    }
}

Abandoned

The onboarding.abandoned event is triggered when an onboarding application has been abandoned, either because signing failed or an application was rejected.

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantIdstringrequired
The merchant identifier (a UUID).
merchantNumberintegeroptional
The numerical merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case onboarding.initated.
dataobjectrequired
The data associated with this event.
- onboardingIdintegerrequired
  The numeric identifier of the onboarding application.
- statusstringrequired
  The current status of the onboarding process.
- reasonstringoptional
  This field is only returned when the signing has failed. Possible values are: 'failed', 'expired', 'cancelled'.

Example

onboarding.abandoned

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.abandoned",
    "data": {
        "onboardingId": 6259,
        "status": "ABANDONED"
    }
}

Reservation created

The payment.reservation.created is an alternative to payment.reservation.created.v2. It is triggered when the amount of the payment has been reserved. But it contains more values, for instance data.cardDetails.threeDSecure.eci)

Payload

idstringrequired
A unique identifier of this event. You can use this identifier to detect whether this event is new or has already been handled by you.
merchantNumberintegerrequired
The merchant number.
timestampstringrequired
The time at which the event occurred formatted according to RFC339, for example 2021-03-23T15:30:55.23Z.
eventstringrequired
The name of the event, in this case payment.reservation.created.
dataobjectrequired
The data associated with this event.
- paymentIdstringrequired
  The payment identifier.
- subscriptionIdstringoptional
  The subscription identifier.
- paymentMethodstringrequired
  The payment method, for example 'Visa' or 'Mastercard'.
- paymentTypestringrequired
  The type of payment. Possible values are: 'CARD', 'INVOICE', 'A2A', 'INSTALLMENT', 'WALLET', and 'PREPAID-INVOICE'.
- amountobjectrequired
  The amount of the reservation.
  - amountinteger (int32)required
    The amount, for example 10000.
  - currencystringrequired
    The currency, for example 'SEK'.

Example

payment.reservation.created.v2

{
    "id": "c25459e92ba54be1925493f987fb05a7",
    "timestamp": "2021-05-04T22:09:08.4342+02:00",
    "merchantNumber": 100017120,
    "event": "payment.reservation.created.v2",
    "data": {
        "paymentMethod": "Visa",
        "paymentType": "CARD",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "02a900006091a9a96937598058c4e474"
    }
}