Skip to main content
API docs by Redocly

checkout-backend-merchant-v3.API (v3)

Download OpenAPI specification:Download

See the Checkout API Guide.

Session

Create a Checkout session

header Parameters
Vipps-System-Name
required
string <= 30 characters
Default: {{system_name}}
Example: Acme Commerce

The name of the ecommerce solution. See http-headers.

Vipps-System-Version
required
string <= 30 characters
Default: {{system_version}}
Example: 3.1.2

The version number of the ecommerce solution. See http-headers.

Vipps-System-Plugin-Name
required
string <= 30 characters
Default: {{system_plugin_name}}
Example: acme-webshop

The name of the ecommerce plugin. See http-headers.

Vipps-System-Plugin-Version
required
string <= 30 characters
Default: {{system_plugin_version}}
Example: 4.5.6

The version number of the ecommerce plugin. See http-headers.

client_id
required
string
Default: {{client_id}}
Example: fb492b5e-7907-4d83-bc20-c7fb60ca35de

Client ID for the merchant (the "username"). See API keys.

client_secret
required
string
Default: {{client_secret}}
Example: Y8Kteew6GE3ZmeycEt6egg==

Client Secret for the merchant (the "password"). See API keys.

Ocp-Apim-Subscription-Key
required
string
Default: {{Ocp-Apim-Subscription-Key}}
Example: 0f14ebcab0eb4b29ae0cb90d91b4a84a

Vipps Subscription key for the API product. See API keys.

Merchant-Serial-Number
required
string
Default: {{merchantSerialNumber}}
Example: 123456

Vipps assigned unique number for a merchant. See API keys.

Idempotency-Key
string
Default: {{Idempotency-Key}}
Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de

Idempotency key for the request, ensures idempotent actions. See Idempotency.

Request Body schema:
One of
reference
string or null

This is the merchant's unique reference to the Checkout Session (as well as the optional payment transaction)

required
object
object or null

If both dynamic and fixed options are specified, dynamic options is provided to the user. If no DynamicOptionsCallback is provided, only fixed logistics options will be used. When using dynamic shipping we recommend that you define logistics.fixedOptions as a backup. If the callback does not resolve successfully within 8 seconds, returns null or an empty list the system will fall back to static options. If no fallback options are provided, the user will be presented with an error and will not be able to continue with the checkout.

type
required
stringPAYMENT
Default: "PAYMENT"
object or null

Information about the customer to be prefilled

If any of the customer information is invalid such as the phone number, the customer will be prompted to input new user information.

required
object
object or null

Responses

Callbacks

Request samples

Content type
Example
{
  • "type": "PAYMENT",
  • "reference": "{{orderId}}",
  • "transaction": {
    },
  • "logistics": {
    },
  • "prefillCustomer": {
    },
  • "merchantInfo": {
    },
  • "configuration": {
    }
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "checkoutFrontendUrl": "string",
  • "pollingUrl": "string"
}

Callback payload samples

Callback
Content type
application/json
{
  • "streetAddress": "string",
  • "postalCode": "string",
  • "region": "string",
  • "country": "string"
}

Get session info

Transaction information, user information and shipping information are included in the response if the SessionState is PaymentInitiated

path Parameters
reference
required
string
Default: "{{orderId}}"

The reference of the session. Example: "123123".

header Parameters
Vipps-System-Name
required
string <= 30 characters
Default: {{system_name}}
Example: Acme Commerce

The name of the ecommerce solution. See http-headers.

Vipps-System-Version
required
string <= 30 characters
Default: {{system_version}}
Example: 3.1.2

The version number of the ecommerce solution. See http-headers.

Vipps-System-Plugin-Name
required
string <= 30 characters
Default: {{system_plugin_name}}
Example: acme-webshop

The name of the ecommerce plugin. See http-headers.

Vipps-System-Plugin-Version
required
string <= 30 characters
Default: {{system_plugin_version}}
Example: 4.5.6

The version number of the ecommerce plugin. See http-headers.

client_id
required
string
Default: {{client_id}}
Example: fb492b5e-7907-4d83-bc20-c7fb60ca35de

Client ID for the merchant (the "username"). See API keys.

client_secret
required
string
Default: {{client_secret}}
Example: Y8Kteew6GE3ZmeycEt6egg==

Client Secret for the merchant (the "password"). See API keys.

Ocp-Apim-Subscription-Key
required
string
Default: {{Ocp-Apim-Subscription-Key}}
Example: 0f14ebcab0eb4b29ae0cb90d91b4a84a

Vipps Subscription key for the API product. See API keys.

Merchant-Serial-Number
required
string
Default: {{merchantSerialNumber}}
Example: 123456

Vipps assigned unique number for a merchant. See API keys.

Idempotency-Key
string
Default: {{Idempotency-Key}}
Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de

Idempotency key for the request, ensures idempotent actions. See Idempotency.

Responses

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "merchantSerialNumber": "string",
  • "reference": "string",
  • "sessionState": "SessionCreated",
  • "paymentMethod": "Wallet",
  • "subscriptionDetails": {
    },
  • "paymentDetails": {
    },
  • "userInfo": {
    },
  • "shippingDetails": {
    },
  • "billingDetails": {
    },
  • "customConsentProvided": true
}

Updates a session

path Parameters
reference
required
string
Default: "{{orderId}}"

The reference of the session. Example: "123123".

header Parameters
Vipps-System-Name
required
string <= 30 characters
Default: {{system_name}}
Example: Acme Commerce

The name of the ecommerce solution. See http-headers.

Vipps-System-Version
required
string <= 30 characters
Default: {{system_version}}
Example: 3.1.2

The version number of the ecommerce solution. See http-headers.

Vipps-System-Plugin-Name
required
string <= 30 characters
Default: {{system_plugin_name}}
Example: acme-webshop

The name of the ecommerce plugin. See http-headers.

Vipps-System-Plugin-Version
required
string <= 30 characters
Default: {{system_plugin_version}}
Example: 4.5.6

The version number of the ecommerce plugin. See http-headers.

client_id
required
string
Default: {{client_id}}
Example: fb492b5e-7907-4d83-bc20-c7fb60ca35de

Client ID for the merchant (the "username"). See API keys.

client_secret
required
string
Default: {{client_secret}}
Example: Y8Kteew6GE3ZmeycEt6egg==

Client Secret for the merchant (the "password"). See API keys.

Ocp-Apim-Subscription-Key
required
string
Default: {{Ocp-Apim-Subscription-Key}}
Example: 0f14ebcab0eb4b29ae0cb90d91b4a84a

Vipps Subscription key for the API product. See API keys.

Merchant-Serial-Number
required
string
Default: {{merchantSerialNumber}}
Example: 123456

Vipps assigned unique number for a merchant. See API keys.

Idempotency-Key
string
Default: {{Idempotency-Key}}
Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de

Idempotency key for the request, ensures idempotent actions. See Idempotency.

Request Body schema:
required
object
required
object

Amounts are specified in minor units. For example: 10.00 NOK should be written as 1000; 20.50 EUR should be written as 2050.

reference
string or null
Deprecated

Deprecated in favor of the top-level The merchant's unique reference for the transaction. Also known as OrderId. Example: "acme-shop-123-order123abc". See https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/

paymentDescription
required
string [ 3 .. 100 ] characters

Description visible to the customer during payment. Example: "One pair of socks".

object or null

Contain descriptions of each item present in the order, and an order bottom line for information regarding the order as a whole.

Responses

Request samples

Content type
{
  • "transaction": {
    }
}

Expire session

path Parameters
reference
required
string
Default: "{{orderId}}"

The reference of the session. Example: "123123".

header Parameters
Vipps-System-Name
required
string <= 30 characters
Default: {{system_name}}
Example: Acme Commerce

The name of the ecommerce solution. See http-headers.

Vipps-System-Version
required
string <= 30 characters
Default: {{system_version}}
Example: 3.1.2

The version number of the ecommerce solution. See http-headers.

Vipps-System-Plugin-Name
required
string <= 30 characters
Default: {{system_plugin_name}}
Example: acme-webshop

The name of the ecommerce plugin. See http-headers.

Vipps-System-Plugin-Version
required
string <= 30 characters
Default: {{system_plugin_version}}
Example: 4.5.6

The version number of the ecommerce plugin. See http-headers.

client_id
required
string
Default: {{client_id}}
Example: fb492b5e-7907-4d83-bc20-c7fb60ca35de

Client ID for the merchant (the "username"). See API keys.

client_secret
required
string
Default: {{client_secret}}
Example: Y8Kteew6GE3ZmeycEt6egg==

Client Secret for the merchant (the "password"). See API keys.

Ocp-Apim-Subscription-Key
required
string
Default: {{Ocp-Apim-Subscription-Key}}
Example: 0f14ebcab0eb4b29ae0cb90d91b4a84a

Vipps Subscription key for the API product. See API keys.

Merchant-Serial-Number
required
string
Default: {{merchantSerialNumber}}
Example: 123456

Vipps assigned unique number for a merchant. See API keys.

Idempotency-Key
string
Default: {{Idempotency-Key}}
Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de

Idempotency key for the request, ensures idempotent actions. See Idempotency.

Responses