Vipps ePayment API (1.1.3)

Download OpenAPI specification:Download

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

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

CreatePayments

Create payment endpoints

Create payment

Create a new payment

Authorizations:

Bearer-Authorization

header Parameters

Idempotency-Key required	string Idempotency key for the request, ensures idempotent actions.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key
Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Vipps-System-Name	string Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good.
Vipps-System-Version	string Example: 5.4.0 The version number of the ecommerce solution.
Vipps-System-Plugin-Name	string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.
Vipps-System-Plugin-Version	string Example: 1.2.1 The version number of the ecommerce plugin (if applicable).

Request Body schema: application/json

New CreatePaymentRequest body.

required	object (Amount) Amount object
	object (Customer) Target customer
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 has to use the `https://` scheme or a custom URL scheme.
userFlow required	string Enum: "PUSH_MESSAGE" "NATIVE_REDIRECT" "WEB_REDIRECT" "QR" The flow for bringing to user to the Vipps Wallet 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`.
	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.

Responses

Request samples

Payload

Content type

application/json

{"amount": {"currency": "NOK",
"value": 1000
},
"customer": {"phoneNumber": 4791234567
},
"customerInteraction": "CUSTOMER_NOT_PRESENT",
"industryData": {"airlineData": {"agencyInvoiceNumber": "string",
"airlineCode": "074",
"airlineDesignatorCode": "KL",
"passengerName": "FLYER / MARY MS.",
"ticketNumber": "string"
}
},
"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"
}

Response samples

201
400
403
409

Content type

application/json

Example

UrlRedirect

{"redirectUrl": "https://landing.vipps.no?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni ",
"reference": "reference-string"
}

QueryPayments

Query payments endpoints

Get 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}$

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key

Responses

Response samples

200

Content type

application/json

{"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 1000
},
"cancelledAmount": {"currency": "NOK",
"value": 1000
},
"capturedAmount": {"currency": "NOK",
"value": 1000
},
"refundedAmount": {"currency": "NOK",
"value": 1000
}
},
"amount": {"currency": "NOK",
"value": 1000
},
"state": "CREATED",
"paymentMethod": {"type": "WALLET",
"cardBin": "540185"
},
"profile": {"sub": "string"
},
"pspReference": "string",
"redirectUrl": "https://landing.vipps.no?token=abc123",
"reference": "reference-string"
}

Get payment event log

Get event log for the specified payment reference id.

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key

Responses

Response samples

200

Content type

application/json

[{"reference": "reference-string",
"pspReference": "string",
"name": "AUTHORIZED",
"paymentAction": "CREATE",
"amount": {"currency": "NOK",
"value": 1000
},
"timestamp": "2019-08-24T14:15:22Z",
"processedAt": "2019-08-24T14:15:22Z",
"idempotencyKey": "string",
"success": true
}
]

AdjustPayments

Adjust payments endpoints

Cancel 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}$

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key
Idempotency-Key required	string Idempotency key for the request, ensures idempotent actions.
Vipps-System-Name	string Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good.
Vipps-System-Version	string Example: 5.4.0 The version number of the ecommerce solution.
Vipps-System-Plugin-Name	string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.
Vipps-System-Plugin-Version	string Example: 1.2.1 The version number of the ecommerce plugin (if applicable).

Responses

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 1000
},
"state": "CREATED",
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 1000
},
"cancelledAmount": {"currency": "NOK",
"value": 1000
},
"capturedAmount": {"currency": "NOK",
"value": 1000
},
"refundedAmount": {"currency": "NOK",
"value": 1000
}
},
"pspReference": "string",
"reference": "reference-string"
}

Capture payment

Capture the given payment

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key
Idempotency-Key required	string Idempotency key for the request, ensures idempotent actions.
Vipps-System-Name	string Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good.
Vipps-System-Version	string Example: 5.4.0 The version number of the ecommerce solution.
Vipps-System-Plugin-Name	string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.
Vipps-System-Plugin-Version	string Example: 1.2.1 The version number of the ecommerce plugin (if applicable).

Request Body schema: application/json

Requested capture modification

required

object (Amount)

Amount object

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

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 1000
},
"state": "CREATED",
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 1000
},
"cancelledAmount": {"currency": "NOK",
"value": 1000
},
"capturedAmount": {"currency": "NOK",
"value": 1000
},
"refundedAmount": {"currency": "NOK",
"value": 1000
}
},
"pspReference": "string",
"reference": "reference-string"
}

Refund payment

Refund the given payment

Authorizations:

Bearer-Authorization

path Parameters

reference

required

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

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key
Idempotency-Key required	string Idempotency key for the request, ensures idempotent actions.
Vipps-System-Name	string Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good.
Vipps-System-Version	string Example: 5.4.0 The version number of the ecommerce solution.
Vipps-System-Plugin-Name	string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.
Vipps-System-Plugin-Version	string Example: 1.2.1 The version number of the ecommerce plugin (if applicable).

Request Body schema: application/json

Requested refund modification

required

object (Amount)

Amount object

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

Response samples

200
400
404
409

Content type

application/problem+json

{"amount": {"currency": "NOK",
"value": 1000
},
"state": "CREATED",
"aggregate": {"authorizedAmount": {"currency": "NOK",
"value": 1000
},
"cancelledAmount": {"currency": "NOK",
"value": 1000
},
"capturedAmount": {"currency": "NOK",
"value": 1000
},
"refundedAmount": {"currency": "NOK",
"value": 1000
}
},
"pspReference": "string",
"reference": "reference-string"
}

ForceApprove

Force approve payment

This endpoint allows developers to approve a payment through the Vipps ePayment API without the use of the Vipps app. This is useful for automated testing. Express checkout is not supported for this endpoint. The endpoint is only available in our test environment. Attempted use of the endpoint in production is not allowed, and will fail. Important: All test users must manually approve at least one payment in Vipps (using the 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}$

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

header Parameters

Merchant-Serial-Number required	string [ 4 .. 6 ] characters ^[0-9]{4,6}$ Example: 123456 The Sales unit's MSN: The unique identifier for the sales unit.
Ocp-Apim-Subscription-Key required	string Example: da7d5b0e18a84aeda961c0c31b75c2a9 APIM Subscription Key

Request Body schema: application/json

Force approve request body

	object (Customer) Target customer
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"
}