Skip to main content

Webhooks

View as Markdown (opens in a new tab)
Install AI tools

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

For troubleshooting, see the full instructions.

You can receive instant notifications about important events, such as successful payments and cancellations. To set up the basic webhook infrastructure, you need to register your webhook URL, as described in the Webhooks API guide. We'll send the real-time notifications about events to the URL you specify.

The ePayment events include:

NameEvent TypeDescription
Createdepayments.payment.created.v1The payment has been initiated. The customer has not yet acted on it.
Abortedepayments.payment.aborted.v1The customer actively stopped the payment before authorization, by tapping cancel.
Expiredepayments.payment.expired.v1The customer did nothing within the payment expiration time, 10 minutes by default.
Cancelledepayments.payment.cancelled.v1The merchant cancelled the uncaptured amount of a payment the customer had already authorized.
Capturedepayments.payment.captured.v1The merchant captured part or all of an authorized payment.
Refundedepayments.payment.refunded.v1The merchant refunded part or all of a captured payment.
Authorizedepayments.payment.authorized.v1The customer accepted the payment in the app.
Terminatedepayments.payment.terminated.v1The merchant cancelled the payment before authorization, using the cancel endpoint.

The event names are easy to mix up: aborted is the customer stopping the payment before authorization, while cancelled is the merchant cancelling a reservation the customer already accepted, and terminated is the merchant stopping the payment before authorization. For the full definitions, see Concepts: State reference.

Info

To get webhooks for these events, the payment must be initiated in the ePayment API.

Register a webhook​

Register to get a webhook when we create a payment. This is the epayments.payment.created.v1 event.

For a complete list of event types, see events.

The events property is an array, so one registration can cover several event types.

For the callback URL, use your webhook server address.

curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data '{  
    "url": "YOUR-CALLBACK-URL", 
    "events": ["epayments.payment.created.v1"] 
}'

To subscribe to more than one event, list them all in the events array:

curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data '{
    "url": "YOUR-CALLBACK-URL",
    "events": [
        "epayments.payment.authorized.v1",
        "epayments.payment.aborted.v1",
        "epayments.payment.expired.v1"
    ]
}'

You will receive a response similar to this, confirming that the webhook registration was successful:

{
   "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "secret":"090a478d-37ff-4e77-970e-d457aeb26a3a"
}
Detecting that the customer did not accept

There is no single "customer did not accept" event. A customer can fail to accept a payment in two different ways, and each has its own event:

  • epayments.payment.aborted.v1: the customer tapped cancel.
  • epayments.payment.expired.v1: the customer did nothing before the payment expired, after 10 minutes by default.

Subscribe to both. If you subscribe to aborted only, you never hear about abandoned payments, and they stay open in your system until you poll for them.

We support up to 25 webhook registrations per event type per MSN. For more about these limits, see webhook limits.

Partners and PSPs

Partners and PSPs can register a webhook for one sales unit or for all the sales units they manage. To register across all your sales units at once, omit Merchant-Serial-Number from the webhook registration request. See Partner/PSP webhooks for more details.

Please note

Webhooks offer a faster user experience than polling, but you should not rely on webhooks alone. In the rare cases where webhooks may be delayed, you should poll the relevant API to get the information you need: GET:/epayment/v1/payments/{reference}.

Depending on your use case, you should set an appropriate timeout for webhooks. If the webhook is not received within that time, you should start polling.

Please follow our polling guidelines.

Webhook payload​

For any webhook, you will receive the following payload, where the only property changing is the name, which will reflect the event type you subscribed to.

msn
required
string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$

The merchant serial number (MSN) for the sales unit.

reference
required
string (ReferenceType) [ 8 .. 64 ] characters ^[a-zA-Z0-9-]{8,64}$

The reference is the unique identifier for the payment, specified when initiating the payment. The reference must be unique for the sales unit (MSN), but is not globally unique, so several MSNs may use the same reference. See the recommendations.

pspReference
required
string (PspReference)

Each payment operation (i.e., create, capture, refund, cancel) will have a unique pspReference, defined by Vipps MobilePay. One of:

  • The Get event log response contains each event and its unique pspReference value.
  • The Get payment response contains the pspReference for the payment creation event.
  • The Adjustment response, returned by Cancel, Capture, and Refund requests, contains the pspReference for the payment creation event.
name
required
string (PaymentEventName)
Enum: "CREATED" "ABORTED" "EXPIRED" "CANCELLED" "CAPTURED" "REFUNDED" "AUTHORIZED" "TERMINATED"

The name of the payment event. Possible values are:

  • CREATED
  • AUTHORIZED
  • CAPTURED
  • CANCELLED
  • REFUNDED
  • ABORTED
  • EXPIRED
  • TERMINATED
required
object (Amount)

Amount object, containing a value and a currency.

timestamp
required
string <date-time>
idempotencyKey
string or null

A unique key that prevents duplicate requests from being processed more than once. See idempotency

success
required
boolean

The outcome of this payment operation: true means that the operation was successful.

object (Shipping Details)

Shipping details for the order.

object (User Details)

User details for the payment.

sub
string

If profile.scope was requested in createPayment, this value will be populated once state is AUTHORIZED. This can be used towards the Userinfo endpoint to fetch required user data.

captureGuaranteedUntil
string <date-time>

The merchant is guaranteed to be able to capture the payment until this timestamp.

Additional information:

  • idempotencyKey is not required, and some webhooks (e.g., CANCELLED) may not supply this value.
  • The pspReference is different for API responses versus webhook notifications (see Understanding pspReference).
  • Profile information in webhooks - If you requested profile information in the payment, the userDetails and sub fields are included in the epayments.payment.authorized.v1 webhook payload automatically.
  • captureGuaranteedUntil is the date until which you're guaranteed a successful capture of the money. See Capture a payment for how to capture, and General info: Capture attempt deadlines for why this date can vary.
  • The webhooks described here are not applicable to the eCom API.

For more information​

For more information about webhooks, see:

Last updated on