ePayment API (1.2.0)

Download OpenAPI specification:Download

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

The ePayment API. See the API Guide for more information.

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 Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api
Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 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

New CreatePaymentRequest body.

required	object (Amount) Amount object, containing a `value` and a `currency`.
	Customer phone number (object) or Personal QR code (object) (Customer) The target customer if the identity is known. The customer can be specified either with phone number or with the user's personal QR code. Specifying more than one of these will result in an error.
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}$ A reference
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 MobilePay app's payment confirmation screen. If `userFlow` is `PUSH_MESSAGE`, a valid value for `customer.phoneNumber` is required.
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 28 days in the future. Can only be combined with `userFlow: PUSH_MESSAGE` or `userFlow: QR`. If ExpiresAt is set, receipt also has to 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.
	object (Receipt)

Responses

Request samples

Payload

Content type

application/json

{"amount": {"currency": "NOK",
"value": 49900
},
"customer": {"phoneNumber": "4791234567"
},
"customerInteraction": "CUSTOMER_NOT_PRESENT",
"industryData": {"airlineData": {"agencyInvoiceNumber": "string",
"airlineCode": "074",
"airlineDesignatorCode": "KL",
"passengerName": "FLYER / MARY MS.",
"ticketNumber": "123-1234567890"
}
},
"paymentMethod": {"type": "WALLET"
},
"profile": {"scope": "string"
},
"reference": "reference-string",
"returnUrl": "https://example.com/redirect?orderId=acme-shop-123-order123abc",
"userFlow": "NATIVE_REDIRECT",
"expiresAt": "2023-02-26T17:32:28Z",
"qrFormat": {"format": "IMAGE/SVG+XML",
"size": 1024
},
"paymentDescription": "string",
"receipt": {"orderLines": [{"name": "Vipps socks",
"id": "1234567890",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 250,
"taxPercentage": 25,
"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"
}
}
}

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api

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": "string",
"redirectUrl": "https://landing.vipps.no?token=abc123",
"reference": "reference-string"
}

Get a payment's event log

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

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api

Responses

Response samples

200

Content type

application/json

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api
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.

Responses

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": "string",
"reference": "reference-string"
}

Capture a payment

Capture the given payment

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api
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) Value: "NOK" Currency code as defined in ISO 4217. eg NOK for Norwegian kroner.
value required	integer <int64> [ 0 .. 65000000 ] Integer value of price in the currency's monetary subunit (e.g., Norwegian øre), or monetary unit where applicable (e.g., Japanese YEN). The type of the monetary unit is defined in ISO 4217.

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": "string",
"reference": "reference-string"
}

Refund a payment

Refund the given payment

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api
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) Value: "NOK" Currency code as defined in ISO 4217. eg NOK for Norwegian kroner.
value required	integer <int64> [ 0 .. 65000000 ] Integer value of price in the currency's monetary subunit (e.g., Norwegian øre), or monetary unit where applicable (e.g., Japanese YEN). The type of the monetary unit is defined in ISO 4217.

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": "string",
"reference": "reference-string"
}

ForceApprove

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 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 MobilePay app before this endpoint can be used for that user.

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

Example: acme-shop-123-order123abc

The primary reference when creating the payment. Similar to orderId in the eCom API. See orderid.

header Parameters

Merchant-Serial-Number required	string (MSNType) [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The merchant serial number (MSN) for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 The Azure API Management subscription key. See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api

Request Body schema: application/json

Force approve request body

	Customer phone number (object) or Personal QR code (object) (Customer) The target customer if the identity is known. The customer can be specified either with phone number 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": "4791234567"
},
"token": "string"
}