ePayment API (1.8.2)

Download OpenAPI specification:Download

URL: https://developer.vippsmobilepay.com/ License: MIT Terms of Service

The ePayment API enables you to create Vipps MobilePay payments for online and in-person payments. See the ePayment API Guide for more details.

CreatePayments

ePayment API endpoint for creating payments.

Create a payment

Create a new payment

Authorizations:

Bearer-Authorization

header Parameters

Idempotency-Key required	string <= 50 characters Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de A unique key that prevents duplicate requests from being processed more than once. See idempotency
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.
Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Vipps-System-Name	string <= 30 characters Example: WooCommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Version	string <= 30 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 30 characters Example: woocommerce-payment The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 30 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json
required

New CreatePaymentRequest body.

required	object (Amount) Amount object, containing a `value` and a `currency`.
	Customer phone number (object) or Personal QR code (object) or Customer token (object) (Customer) The target customer if the identity is known. The customer can be specified either with phone number, the customer token or with the user's personal QR code Specifying more than one of these will result in an error.
minimumUserAge	integer or null [ 0 .. 100 ] Minimum age in years required for the customer to make the purchase.
customerInteraction	string Default: "CUSTOMER_NOT_PRESENT" Enum: "CUSTOMER_PRESENT" "CUSTOMER_NOT_PRESENT" The type of customer interaction that triggers the purchase. `CUSTOMER_PRESENT`: The customer is physically present at the point of sale, typically in a store. `CUSTOMER_NOT_PRESENT`: The customer is not physically present, typically for online or remote payments.
	object (IndustryData) Additional compliance data related to the transaction.
required	object (PaymentMethod)
	object (Profile)
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.
returnUrl	string <= 2500 characters The URL the user is returned to after the payment session. The URL must use the `https://` scheme or a custom URL scheme.
userFlow required	string Enum: "PUSH_MESSAGE" "NATIVE_REDIRECT" "WEB_REDIRECT" "QR" The flow for bringing the user to the Vipps or MobilePay app's payment confirmation screen. If `userFlow` is `PUSH_MESSAGE`, a valid value for `customer` is required. If `userFlow` is `WEB_REDIRECT`, a valid value for `returnUrl` is required. `WEB_REDIRECT` is the normal flow for browser-based payment flows. If on a mobile device, the Vipps or MobilePay app will open. A valid value for `returnUrl` is required. Otherwise, the landing page will open. `PUSH_MESSAGE` is to skip the landing page for payments initiated on a device other than the user's phone. The user gets a push message that opens the payment in the app. This requires a valid `customer` field. `QR` returns a QR code that can be scanned to complete the payment. `NATIVE_REDIRECT` is not recommended, except in some cases where merchant doesn’t have web presence. It provides automatic app-switch between the merchant's native app and the Vipps or MobilePay app. We recommend using `WEB_REDIRECT` instead.
expiresAt	string or null^((?:(\d{4}-\d{2}-\d{2})(T\|t)(\d{2}:\d{2}:\d{... Only relevant for Long-living payment requests, which require special approval. The payment will expire at the given date and time. The format must adhere to RFC 3339. The value must be more than 10 minutes and less than 60 days in the future. If `ExpiresAt` is set, `receipt` also must be set. See Long-living legal,
	object or null Optional setting that is only applicable when `userFlow` is set to `QR`. This is used to set the format for the QR code.
paymentDescription	string [ 3 .. 100 ] characters The payment description summary that will be provided to the user through the Vipps MobilePay app, the business portal, and the settlement files. See the recommendations for description text.
	object (Receipt)
	object or null (Metadata) <= 5 properties Metadata is a key-value map that can be used to store additional information about the payment. The metadata is not used by Vipps MobilePay, but is passed through in the `GetPaymentResponse` object. Key length is limited to 100 characters, and value length is limited to 500 characters. Max capacity is 5 key-value pairs.
receiptUrl	string or null The URL where a receipt can be viewed or downloaded. The URL must use the `https://` scheme or a custom URL scheme.
	object (Shipping) Shipping options used in Express. These can be either `dynamicOptions` or `fixedOptions`. See the Express section of the ePayment API guide for more details.
	object (CardPassthrough) PSPs only: Card passthrough details for PSP initiated card payments.

Responses

Callbacks

Request samples

Payload

Content type

application/json

{"amount": {"currency": "NOK",
"value": 49900
},
"customer": {"phoneNumber": "4712345678"
},
"minimumUserAge": 16,
"customerInteraction": "CUSTOMER_NOT_PRESENT",
"industryData": {"airlineData": {"agencyInvoiceNumber": "string",
"airlineCode": "074",
"airlineDesignatorCode": "KL",
"passengerName": "FLYER / MARY MS.",
"ticketNumber": "123-1234567890"
}
},
"paymentMethod": {"type": "WALLET",
"blockedSources": ["COMMERCIAL_CARDS"
]
},
"profile": {"scope": "name phoneNumber"
},
"reference": "acme-shop-123-order123abc",
"returnUrl": "https://example.com/redirect?orderId=acme-shop-123-order123abc",
"userFlow": "WEB_REDIRECT",
"expiresAt": "2023-02-26T17:32:28Z",
"qrFormat": {"format": "IMAGE/SVG+XML",
"size": 1024
},
"paymentDescription": "Temporary reservation of maximum amount. You will only be charged for the actual use.",
"receipt": {"orderLines": [{"name": "socks",
"id": "1234567890",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 250,
"taxPercentage": 25,
"taxRate": 2500,
"unitInfo": {"unitPrice": 0,
"quantity": "0.822",
"quantityUnit": "PCS"
},
"discount": 2000,
"productUrl": "https://example.com/store/socks",
"isReturn": false,
"isShipping": false
}
],
"bottomLine": {"currency": "NOK",
"tipAmount": 2000,
"giftCardAmount": 20000,
"posId": "string",
"totalAmount": 0,
"totalTax": 0,
"totalDiscount": 0,
"shippingAmount": 0,
"shippingInfo": {"amount": 1000,
"amountExcludingTax": 1000,
"taxAmount": 250,
"taxPercentage": 25
},
"paymentSources": {"giftCard": 0,
"card": 0,
"voucher": 0,
"cash": 0
},
"barcode": {"format": "EAN-13",
"data": "string"
},
"receiptNumber": "string",
"terminalId": "string"
}
},
"metadata": {"key1": "value1",
"key2": "value2",
"key3": "value3"
},
"receiptUrl": "https://example.com/receipt/9876543210",
"shipping": {"dynamicOptions": {"callbackUrl": "string",
"callbackAuthorizationToken": "string"
},
"fixedOptions": [{"isDefault": true,
"priority": 0,
"type": "HOME_DELIVERY",
"brand": "POSTEN",
"options": [{"id": "pickup-123",
"isDefault": true,
"amount": {"currency": "NOK",
"value": 49900
},
"name": "Pickup at Posten Store",
"priority": 1,
"meta": "Keybox code required",
"estimatedDelivery": "string"
}
]
}
]
},
"cardPassthrough": {"pspReference": "psp-reference",
"cardCallbackUrl": "https://callback.example",
"allowedCardTypes": ["VISA_DEBIT"
],
"preferVisaPartOfVisaDankort": false,
"publicEncryptionKeyId": "public-key-id"
}
}

Response samples

201
400
403
409

Content type

application/json

Example

UrlRedirect

{"redirectUrl": "https://landing.vipps.no?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni",
"reference": "acme-shop-123-order123abc"
}

Callback payload samples

Callback

POST: Merchant dynamic shipping callback (for Express only)

Content type

application/json;charset=UTF-8

{"reference": "acme-shop-123-order123abc",
"AddressLine1": "Robert Levins gate 5",
"AddressLine2": "Apt 3",
"City": "Oslo",
"PostCode": "0154",
"Country": "NO"
}

QueryPayments

ePayment API endpoints for getting payment details and events.

Get a payment

Get a payment object by its reference id.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.

Responses

Response samples

200

Content type

application/json

{"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 49900
},
"cancelledAmount": {"currency": "NOK",
"value": 49900
},
"capturedAmount": {"currency": "NOK",
"value": 49900
},
"refundedAmount": {"currency": "NOK",
"value": 49900
}
},
"amount": {"currency": "NOK",
"value": 49900
},
"state": ["AUTHORIZED"
],
"paymentMethod": {"type": "WALLET",
"cardBin": "540185"
},
"profile": {"sub": "string"
},
"pspReference": "3343121302",
"redirectUrl": "https://landing.vipps.no?token=abc123",
"reference": "acme-shop-123-order123abc",
"metadata": {"key1": "value1",
"key2": "value2",
"key3": "value3"
},
"shippingDetails": {"address": {"addressLine1": "Robert Levins gate 5",
"addressLine2": "Att: Rune Garborg",
"city": "Oslo",
"country": "NO",
"postCode": "0154"
},
"shippingCost": 9900,
"shippingOptionId": "posten-servicepakke-1",
"shippingOptionName": "A-post"
},
"userDetails": {"email": "user@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
"mobileNumber": "4712345678",
"dateOfBirth": "1988-12-31",
"addresses": [{"addressLine1": "Robert Levins gate 5",
"addressLine2": "Att: Rune Garborg",
"city": "Oslo",
"country": "NO",
"postCode": "0154"
}
]
}
}

Get a payment's event log

Get event log for the specified payment's reference id.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.

Responses

Response samples

200

Content type

application/json

[{"reference": "acme-shop-123-order123abc",
"pspReference": "3343121302",
"name": "AUTHORIZED",
"amount": {"currency": "NOK",
"value": 49900
},
"timestamp": "2022-12-31T00:00:00Z",
"idempotencyKey": "fb492b5e-7907-4d83-ba20-c7fb60ca35de",
"success": true
}
]

AdjustPayments

ePayment API endpoints for cancelling, capturing, and refunding payments.

Cancel a payment

Cancel the payment with the specified reference id.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.
Vipps-System-Name	string <= 30 characters Example: WooCommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Version	string <= 30 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 30 characters Example: woocommerce-payment The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 30 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json
optional

New CancelModificationRequest body.

cancelTransactionOnly

boolean

Only cancel transaction if it has not been authorized. If this flag is set and the transaction has been authorized, the reserved amount will not be canceled.

Responses

Request samples

Payload

Content type

application/json

{"cancelTransactionOnly": true
}

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 49900
},
"state": ["AUTHORIZED"
],
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 49900
},
"cancelledAmount": {"currency": "NOK",
"value": 49900
},
"capturedAmount": {"currency": "NOK",
"value": 49900
},
"refundedAmount": {"currency": "NOK",
"value": 49900
}
},
"pspReference": "3343121302",
"reference": "acme-shop-123-order123abc"
}

Capture a payment

Capture the given payment

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.
Idempotency-Key required	string <= 50 characters Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de A unique key that prevents duplicate requests from being processed more than once. See idempotency
Vipps-System-Name	string <= 30 characters Example: WooCommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Version	string <= 30 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 30 characters Example: woocommerce-payment The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 30 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

Requested capture modification

required

object (Amount)

Amount object, containing a value and a currency.

currency

required

string (Currency)

Enum: "NOK" "DKK" "EUR" "SEK" "USD" "GBP"

ISO 4217 currency code. Supported values: NOK, DKK, EUR (all merchants), and SEK, USD, GBP (Payment Services Providers only).

value

required

integer <int64> [ 0 .. 65000000 ]

Amount in minor units (the smallest unit of the currency). For example, 10.00 EUR is 1000.

Minimum amounts:

NOK: 100 (1.00 NOK)
DKK: 1 (0.01 DKK)
EUR: 1 (0.01 EUR)
SEK: 100 (1.00 SEK) - Payment Services Providers only
USD: 1 (0.01 USD) - Payment Services Providers only
GBP: 1 (0.01 GBP) - Payment Services Providers only

Maximum: 65000000 (e.g., 650000.00 NOK).

Responses

Request samples

Payload

Content type

application/json

{"modificationAmount": {"currency": "NOK",
"value": 49900
}
}

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 49900
},
"state": ["AUTHORIZED"
],
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 49900
},
"cancelledAmount": {"currency": "NOK",
"value": 49900
},
"capturedAmount": {"currency": "NOK",
"value": 49900
},
"refundedAmount": {"currency": "NOK",
"value": 49900
}
},
"pspReference": "3343121302",
"reference": "acme-shop-123-order123abc"
}

Refund a payment

Refund the given payment

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.
Idempotency-Key required	string <= 50 characters Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de A unique key that prevents duplicate requests from being processed more than once. See idempotency
Vipps-System-Name	string <= 30 characters Example: WooCommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Version	string <= 30 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 30 characters Example: woocommerce-payment The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 30 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

Requested refund modification

required

object (Amount)

Amount object, containing a value and a currency.

currency

required

string (Currency)

Enum: "NOK" "DKK" "EUR" "SEK" "USD" "GBP"

ISO 4217 currency code. Supported values: NOK, DKK, EUR (all merchants), and SEK, USD, GBP (Payment Services Providers only).

value

required

integer <int64> [ 0 .. 65000000 ]

Amount in minor units (the smallest unit of the currency). For example, 10.00 EUR is 1000.

Minimum amounts:

NOK: 100 (1.00 NOK)
DKK: 1 (0.01 DKK)
EUR: 1 (0.01 EUR)
SEK: 100 (1.00 SEK) - Payment Services Providers only
USD: 1 (0.01 USD) - Payment Services Providers only
GBP: 1 (0.01 GBP) - Payment Services Providers only

Maximum: 65000000 (e.g., 650000.00 NOK).

Responses

Request samples

Payload

Content type

application/json

{"modificationAmount": {"currency": "NOK",
"value": 49900
}
}

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 49900
},
"state": ["AUTHORIZED"
],
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 49900
},
"cancelledAmount": {"currency": "NOK",
"value": 49900
},
"capturedAmount": {"currency": "NOK",
"value": 49900
},
"refundedAmount": {"currency": "NOK",
"value": 49900
}
},
"pspReference": "3343121302",
"reference": "acme-shop-123-order123abc"
}

ForceApprove

ePayment API endpoint used for testing. Authorize payments through the API.

Force approve a payment

This endpoint is only available in the test environment. It allows developers to approve a payment through the ePayment API without the use of the Vipps or MobilePay app. This is useful for automated testing. Express checkout is not supported for this endpoint. Attempted use in production is not allowed, and will fail. Important: All test users must manually approve at least one payment in the Vipps or MobilePay app before this endpoint can be used for that user.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

Example: acme-shop-123-order123abc

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.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ Example: 1234567 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The subscription key for a sales unit. See API keys.

Request Body schema: application/json

Force approve request body

	Customer phone number (object) or Personal QR code (object) or Customer token (object) (Customer) The target customer if the identity is known. The customer can be specified either with phone number, the customer token or with the user's personal QR code Specifying more than one of these will result in an error.
token	string The token value received in the `redirectUrl` property in the Create payment response

Responses

Request samples

Payload

Content type

application/json

{"customer": {"phoneNumber": "4712345678"
},
"token": "string"
}

Merchant Endpoints

These endpoints are used by Vipps MobilePay to communicate with you as the merchant, and must be implemented on your side.

Merchant dynamic shipping callback

Implement this endpoint on your server to provide dynamic shipping options. Vipps MobilePay will POST to this URL with the user's address and a token. Your response must include an array of shipping groups. Your URL must use HTTPS and a common port (80, 443, or 8080). See the API guide for URL validation requirements.

Authorizations:

Bearer-Authorization

header Parameters

Authorization

string^[a-zA-Z0-9-]{1,50}$

Example: ae0cb90d91b4a84a

The token provided by the merchant in the create payment request, in the shipping.dynamicOptions parameter. We use this token when making the dynamic shipping groups call to the merchant's server, thus allowing the merchant to authenticate the request.

Request Body schema: application/json;charset=UTF-8
required

Available shipping groups.

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.
AddressLine1 required	string The first line of the recipient's address (e.g., street name and number).
AddressLine2	string or null Additional address information, such as apartment, suite, or attention line. Optional.
City required	string The city or locality of the address.
PostCode required	string The postal code of the address in local country format.
Country required	string The country of the address in ISO 3166-1 alpha-2 format (e.g., NO for Norway, DK for Denmark, FI for Finland).

Responses

Request samples

Payload

Content type

application/json;charset=UTF-8

{"reference": "acme-shop-123-order123abc",
"AddressLine1": "Robert Levins gate 5",
"AddressLine2": "Apt 3",
"City": "Oslo",
"PostCode": "0154",
"Country": "NO"
}

Response samples

200

Content type

application/json;charset=UTF-8

{"groups": [{"isDefault": true,
"priority": 0,
"type": "HOME_DELIVERY",
"brand": "POSTEN",
"options": [{"id": "pickup-123",
"isDefault": true,
"amount": {"currency": "NOK",
"value": 49900
},
"name": "Pickup at Posten Store",
"priority": 1,
"meta": "Keybox code required",
"estimatedDelivery": "string"
}
]
}
]
}

PSP card callback

This endpoint is only relevant if you are a PSP (Payment Services Provider).

This is the endpoint where Vipps MobilePay will send card information to the PSP as part of the card passthrough flow. Either a network token or an encrypted PAN will be sent, depending on the cardDataType field in the request. The PSP should use this information to perform the authorization and return the result.

The PSP must respond with a status of RESERVE, SOFT_DECLINE, or FAIL.

If the status is RESERVE, the networkTransactionReference must be included.
If the status is SOFT_DECLINE, the softDeclineUrl must be included.
If the status is FAIL, errorCode and errorMessage must be included.

Request authentication

All requests to this endpoint are signed using HMAC-SHA256 with the PSP's client_secret as the signing key. To verify a received request:

Verify payload integrity — compute the SHA-256 hash of the raw request body, base64-encode it, and compare the result against the x-ms-content-sha256 header value.
Verify the signature — construct the string to sign by concatenating the HTTP method, path and query string, date, host, and content hash in the following format (note: \n newlines, not \r\n):
```
POST\n<pathAndQuery>\n<date>;<host>;<contentHash>
```
Sign this string with HMAC-SHA256 using the PSP's client_secret and base64-encode the result. It must match the Signature value in the Authorization header.

Both Authorization and X-Vipps-Authorization use the same signing scheme and can be verified independently.

Authorizations:

Bearer-Authorization

header Parameters

Authorization required	string Example: HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=agAiSyogQbDHpeucoNwYz+yAr5nJ+v+zasdkSbqzv+U= HMAC-SHA256 authentication header. Format: `HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=<signature>`. The signature is computed over the request method, path, date, host, and content hash, signed with the PSP's `client_secret`.
X-Vipps-Authorization required	string Example: HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=agAiSyogQbDHpeucoNwYz+yAr5nJ+v+zasdkSbqzv+U= Secondary HMAC-SHA256 authorization header, identical in format to `Authorization`. Used for Vipps MobilePay internal routing and validation.
x-ms-date required	string Example: Mon, 18 Feb 2026 15:33:00 GMT The UTC date and time of the request in RFC 1123 format. Used as part of the HMAC signature.
x-ms-content-sha256 required	string Example: lNlsp1XA03N34HrQsVzPgJKtC+r7l/RBF4V3JQUWMj4= Base64-encoded SHA-256 hash of the raw request body. Used to verify that the content has not been tampered with.

Request Body schema: application/json
required

pspReference required	string Your unique reference for this payment, as provided in the create payment request.
authorizationAttemptId required	string <uuid> Unique identifier for this authorization attempt.
merchantSerialNumber required	string The merchant serial number for the payment.
required	object (Amount) Amount object, containing a `value` and a `currency`.
softDeclineCompletedRedirectUrl	string URL to redirect to after a soft decline is resolved.
required	object (CardInfo) Card details included in the PSP card callback.

Responses

Request samples

Payload

Content type

application/json

{"pspReference": "7686f7788898767977",
"authorizationAttemptId": "731C95C5-7E8B-40C3-A6EA-713B24694E6E",
"merchantSerialNumber": "123456",
"softDeclineCompletedRedirectUrl": "https://vipps.no/mobileintercept?token=aY32sdsds423=",
"cardInfo": {"maskedCardNumber": "47969485XXXX1234",
"cardType": "VISA-DEBIT",
"cardIssuedInCountryCode": "DK",
"cardDataType": "TOKEN",
"networkToken": {"number": "5000000000000000001",
"cryptogram": "aFgdgjdkfgjdFDF=",
"expiryMonth": "03",
"expiryYear": "2030",
"tokenType": "VISA",
"eci": "7",
"paymentAccountReference": "5001BO8B9NXVVIXCT0HAJU98I512Z"
}
},
"amount": {"value": 1000,
"currency": "DKK"
}
}

Response samples

200

Content type

application/json

Example

Successful reservation

{"status": "RESERVE",
"networkTransactionReference": "ABC123XYZ"
}

ePayment API (1.8.2)

CreatePayments

Create a payment

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Callbacks

Request samples

Response samples

Callback payload samples

QueryPayments

Get a payment

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Get a payment's event log

Authorizations:

path Parameters

header Parameters

Responses

Response samples

AdjustPayments

Cancel a payment

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Capture a payment

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Refund a payment

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

ForceApprove

Force approve a payment

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Merchant Endpoints

Merchant dynamic shipping callback

Authorizations:

header Parameters

Request Body schema: application/json;charset=UTF-8required

Responses

Request samples

Response samples

PSP card callback

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json;charset=UTF-8
required

Request Body schema: application/json
required