ePayment API (1.6.0)

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

Create payment endpoints

Create a payment

Create a new payment

Authorizations:

Bearer-Authorization

header Parameters

Idempotency-Key required	string <= 50 characters Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de Idempotency key for the request, ensures idempotent actions. 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 .. 7 ] characters ^[0-9]{4,7}$ 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` means that the customer is physically present at the point of sale when the payment is made, typically in a store.
	object (IndustryData) Additional compliance data related to the transaction.
required	object (PaymentMethod)
	object (Profile)
reference required	string (ReferenceType) [ 8 .. 50 ] characters ^[a-zA-Z0-9-]{8,50}$ 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 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{... 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. Can only be combined with `userFlow: PUSH_MESSAGE` or `userFlow: QR`. If `ExpiresAt` is set, `receipt` also must be set.
	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 app, the merchant portal, and the settlement files. See the recommendations.
	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.

Responses

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"
}

Response samples

201
400
403
409

Content type

application/json

Example

UrlRedirect

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

QueryPayments

Query payments endpoints

Get a payment

Get a payment object by its reference id.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

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 .. 7 ] characters ^[0-9]{4,7}$ 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": "CREATED",
"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"
}
}

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 .. 50 ] characters ^[a-zA-Z0-9-]{8,50}$

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 .. 7 ] characters ^[0-9]{4,7}$ 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

Adjust payments endpoints

Cancel a payment

Cancel the payment with the specified reference id.

Authorizations:

Bearer-Authorization

path Parameters

Reference

required

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

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 .. 7 ] characters ^[0-9]{4,7}$ 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 Idempotency key for the request, ensures idempotent actions. 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
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": "CREATED",
"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 .. 50 ] characters ^[a-zA-Z0-9-]{8,50}$

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 .. 7 ] characters ^[0-9]{4,7}$ 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 Idempotency key for the request, ensures idempotent actions. 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" Available types of currency are NOK, DKK, and EUR.
value required	integer <int64> [ 0 .. 65000000 ] Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 NOK should be written as 1000. The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.

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": "CREATED",
"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 .. 50 ] characters ^[a-zA-Z0-9-]{8,50}$

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 .. 7 ] characters ^[0-9]{4,7}$ 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 Idempotency key for the request, ensures idempotent actions. 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" Available types of currency are NOK, DKK, and EUR.
value required	integer <int64> [ 0 .. 65000000 ] Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 NOK should be written as 1000. The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.

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": "CREATED",
"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

Force approve payments endpoints

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 .. 50 ] characters ^[a-zA-Z0-9-]{8,50}$

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 .. 7 ] characters ^[0-9]{4,7}$ 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"
}

ePayment API (1.6.0)

CreatePayments

Create a payment

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response 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

Request Body schema: application/json
required

Request Body schema: application/json
optional