> **Description:** Create payments with detailed request parameters and response handling. # Create payment A merchant system will send a payment request to the user when they select to pay with Vipps/MobilePay. When an ePayment is created, the customer receives a push notification for approval. If not approved or completed, no further notifications are sent. The payment status remains available in the app for the customer to view. User flows ```mermaid %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%% flowchart TD Payment --> Wallet[fa:fa-mobile paymentMethod: WALLET] Wallet --> WEB_REDIRECT[fa:fa-desktop userFlow: WEB_REDIRECT] Wallet --> NATIVE_REDIRECT[fa:fa-mobile userFlow: NATIVE_REDIRECT] Wallet --> PUSH_MESSAGE[fa:fa-bell userFlow: PUSH_MESSAGE] Wallet --> QR[fa:fa-qrcode userFlow: QR] Payment --> Card[fa:fa-credit-card paymentMethod:CARD] Card --> CARD_WEB_REDIRECT[fa:fa-desktop userFlow: WEB_REDIRECT] ``` Payment method and user flow options: A payment can use payment method WALLET, which supports user flows WEB_REDIRECT (desktop), NATIVE_REDIRECT (mobile), PUSH_MESSAGE (push notification), and QR (QR code). Alternatively, a payment can use payment method CARD, which supports only the WEB_REDIRECT user flow. ## Authorization All ePayment API requests must include a valid Bearer token in the `Authorization` header. See [Authorization](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#authorization) for how to obtain one. ## The create payment request Send a [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) request with the [required headers](#header) and [required parameters](#parameters). If you are a Payment Service Provider, see **[PSP ePayment integration](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md)** for more details. **Example create payment request** This sends a Vipps/MobilePay payment request to the customer. ```bash curl -X POST https://apitest.vipps.no/epayment/v1/payments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \ -H "Merchant-Serial-Number: YOUR-MSN" \ -H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \ -H "Vipps-System-Name: acme" \ -H "Vipps-System-Version: 3.1.2" \ -H "Vipps-System-Plugin-Name: acme-webshop" \ -H "Vipps-System-Plugin-Version: 4.5.6" \ -d '{ "amount":{ "currency":"NOK", "value":6000 }, "customer":{ "phoneNumber":"4712345678" }, "paymentMethod":{ "type":"WALLET" }, "reference":"acme-shop-123-1234589", "paymentDescription": "", "returnUrl":"https://example.com/redirect?orderId=1512202", "userFlow":"WEB_REDIRECT", }' ``` ## Parameters ### Header **Required** * `Authorization` - Bearer-Authorization. The access token is a base64-encoded string that is required for all API calls. * `Idempotency-Key` - Idempotency key for the request, ensures idempotent actions. See [Idempotency](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md#idempotency) * `Ocp-Apim-Subscription-Key` - The subscription key for a sales unit. See [API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys). * `Merchant-Serial-Number` - The Merchant Serial Number is a unique identifier that is defined when a sales unit is created. See [How to find the Merchant Serial Number](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-merchant-serial-number) **Optional** * `Psp-Id` - Only used by Payment Service Providers. If you are a PSP, see [PSP ePayment integration](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md). There are several optional [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) that are helpful for debugging (e.g., `Vipps-System-Name`). ### Body **Required parameters** * `amount` - Amount object, containing a value and a currency. Values are in **minor units** (øre for NOK and DKK, cents for EUR) -- for example, `49900` = 499 NOK. The currency must match the currency for your sales unit. The minimum amounts allowed are: NOK 100 øre, DKK 1 øre, EUR 1 cent * `paymentMethod` - Type must be either `WALLET` or `CARD` (see [`paymentMethod`](#paymentmethod)). * `reference` - 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 [orderId / reference recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid.md). * `userFlow` - The normal flow is `WEB_REDIRECT`. `QR` creates a one-time QR which the user scans to pay with Vipps/MobilePay. * `customer` - Required for `userFlow` of `PUSH_MESSAGE`. The customer phone number or login token. * `returnUrl` - Required for `userFlow` of `WEB_REDIRECT`. The URL the user is returned to after the payment session. The URL must use the https:// scheme or a custom URL scheme. **Optional parameters for special features** The following parameters are used for [special features](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/README.md): * `receipt` - ([Set order details](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/pre-built-order-management-api-integration.md)) The order details for a payment. * `shipping` - ([Express](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/express.md)) Display shipping delivery options and prices in the Vipps/MobilePay app. * `profile` - ([Profile sharing](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/profile-sharing.md)) Request the user's profile information. * `expiresAt` - ([Long-living payments](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/long-living-payments.md)) Extend the payment deadline. * `minimumUserAge` - ([Minimum user age](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/minimum-user-age.md)) Limit payments to people over a minimum age. * `customerInteraction` - ([Specify customer present](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/customer-present-payments.md)) Should be specified when customers are physically present, specify `"customerInteraction": "CUSTOMER_PRESENT"`. * `blockedSources` - ([Block payment sources](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/block-payment-sources.md)) Danish and Finnish sales units can block payment sources when using `WALLET` as payment method type. * `metadata` - ([Add metadata](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/metadata.md)) Add metadata to the payment. * `cardPassthrough` - Only used by Payment Service Providers. If you are a PSP, see [PSP ePayment integration](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md). ## `paymentMethod` The [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) endpoint supports both *wallet* (i.e., the Vipps or MobilePay app) and freestanding card payments (e.g., VISA, Mastercard), when card details are entered. Each payment type offers separate user flows. These are specified in `paymentMethod.type` as: * `WALLET` - normal flow, payment is through the Vipps/MobilePay app * `CARD` - payment is through [freestanding cards](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/freestanding-card-payments.md) * `CARD_PASSTHROUGH` - Only used by Payment Service Providers. If you are a PSP, see [PSP ePayment integration](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md). Example: ```json "paymentMethod":{ "type":"WALLET" } ``` ### `WALLET` `WALLET` is the normal payment method where the user pays through the Vipps or MobilePay app. This includes delegated Strong Customer Authentication (SCA), where the login to the app eliminates the need for a separate SCA step. `WALLET` payments include retry functionality such that, if the user attempts to pay with a declined card, they can retry with a different card for the same payment process. ### `CARD` With `CARD` as the payment method, the user pays with a freestanding card instead of Vipps/MobilePay. They enter the card details into a form and then complete the 3D Secure step-up for SCA. For more information about card payments, see: * [Features: Freestanding cards](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/freestanding-card-payments.md) * [General info: Card payments](https://developer.vippsmobilepay.com/docs/knowledge-base/payments.md#card-payments) **NOTE** Card payment (`CARD`) is not available in the test environment. ### `CARD_PASSTHROUGH` This is only used by Payment Service Providers. If you are a PSP, see [PSP ePayment integration](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md). ## `userFlow` The `userFlow` parameter specifies how the API should handle the payment and how the user experience will be. In the [create payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/create.md) request, specify `userFlow` as one of the following options (usually `"userFlow": "WEB_REDIRECT"`): | `userFlow` | Description | | ----------------- | ---------------------------------------------------- | | [`WEB_REDIRECT`](#web_redirect) | `WEB_REDIRECT` (the normal flow) works for browsers and native apps by handling the app-switching. If the user is on a mobile device with the Vipps or MobilePay app installed, it will open automatically. Otherwise, the [landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) will open. A valid value for `returnUrl` is required. | | [`PUSH_MESSAGE`](#push_message) | `PUSH_MESSAGE` (requires approval) is specified 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 Vipps or MobilePay app. A valid value for `customer` is required.| | [`QR`](#qr) | The `QR` flow returns a QR code that is scanned by the user to complete the payment. | | [`NATIVE_REDIRECT`](#native_redirect) | `NATIVE_REDIRECT` (not recommended, except in some cases where merchant doesn't have web presence) provides automatic app-switch between the merchant's native app and the Vipps or MobilePay app. We recommend using `WEB_REDIRECT` instead. | ### `WEB_REDIRECT` The `WEB_REDIRECT` flow provides fallback to the landing page in case the Vipps or MobilePay app aren't installed. This is the recommended flow for webshops and apps. `WEB_REDIRECT` is more secure than `NATIVE_REDIRECT` and offers better cross-platform compatibility. Please see [General info: App flow recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow.md) for more details. This flow is applicable for both `WALLET` and `Card` payment flows. Specify `"userFlow": "WEB_REDIRECT"` in the [create payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/create.md) request. For example: ```bash curl -X POST https://apitest.vipps.no/epayment/v1/payments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \ -H "Merchant-Serial-Number: YOUR-MSN" \ -H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \ -H "Vipps-System-Name: acme" \ -H "Vipps-System-Version: 3.1.2" \ -H "Vipps-System-Plugin-Name: acme-webshop" \ -H "Vipps-System-Plugin-Version: 4.5.6" \ -d '{ "amount": { "value": 49900, "currency": "NOK" }, "paymentMethod": { "type": "WALLET" }, "customer": { "phoneNumber": 4712345678 }, "reference": 58712432, "userFlow": "WEB_REDIRECT", "returnUrl": "http://example.com/redirect?reference=58712432", "paymentDescription": "descriptive" }' ``` The [`WALLET` payment method](#wallet) is the normal flow. In this flow there are two scenarios: * When the user is on a mobile device with the Vipps or MobilePay app installed, we will automatically do an app-switch to the app, eliminating the need to enter the phone number, and avoiding any potential friction. This is the normal flow on mobile devices. The [landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) should never be seen on a mobile device with the app installed. * When the user is on a device *without* the Vipps or MobilePay app installed (a PC/Mac, a tablet, or a second phone), we will open the [landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) where the user can enter the phone number (browsers may remember the phone number, simplifying this step). In the [`CARD` flow](#card), regardless of whether the user is on a desktop or mobile device, the card entry page will open. **Important information for the default `WEB_REDIRECT` flow** The API response from [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) contains the `redirectUrl` (previously called "deeplink URL"). It is **crucial** that this URL is opened directly, without making any changes to it. Do *not* redirect to the URL, but *open it* using the default URL opening functionality on the phone's operating system. Never open the URL in a [web view, iframe or similar](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md#can-i-show-the-landing-page-in-an-iframe), as that will break the flow. On phones, the phone operating system will recognize the URL and automatically do an app-switch to the Vipps MobilePay app using universal linking. On other devices, the [landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) will be shown, so the user can enter the phone number, get a push notification on the phone, and confirm the payment in the Vipps MobilePay app on the phone. **Important:** Do not attempt to detect if the Vipps MobilePay app is installed, as users must be able to initiate a payment flow on any device without the app, and complete it on a device with the Vipps MobilePay app installed. This is handled automatically by us, based on years of continuous improvement, ensuring the best possible success rate. Please see [General info: App flow recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow.md) for more details. ### `PUSH_MESSAGE` **Special approval required** Sales units must be approved to use this user flow because it skips the [Vipps/MobilePay landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md#skip-landing-page). To request this feature, please contact your key account manager, your partner manager, or [customer service](https://help.vippsmobilepay.com/). Applicable only for `WALLET` payments initiated on a device other than the user's device (e.g., a Point of Sale). Specify `"userFlow": "PUSH_MESSAGE"`. A valid `customer` is required. Example: ```bash curl -X POST https://apitest.vipps.no/epayment/v1/payments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \ -H "Merchant-Serial-Number: YOUR-MSN" \ -H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \ -H "Vipps-System-Name: acme" \ -H "Vipps-System-Version: 3.1.2" \ -H "Vipps-System-Plugin-Name: acme-webshop" \ -H "Vipps-System-Plugin-Version: 4.5.6" \ -d '{ "amount": { "value": 15000, "currency": "DKK" }, "paymentMethod": { "type": "WALLET" }, "customer": { "phoneNumber": "4512345678" }, "reference": 21203831704360461822, "userFlow": "PUSH_MESSAGE" }' ``` This will create a push message on the user's phone where they can approve the payment. **INFO** Using `PUSH_MESSAGE` (and skipping the landing page) is only allowed when it is not possible to show the landing page, when the payment is initiated on a device that the user does not own or control. This includes: * Not on the user's phone * Not on the user's computer * On a device that has no user-facing display where the landing page can be shown, such as physical points of sale (POS) solutions or vending machines. #### Troubleshooting ##### "PUSH_MESSAGE flow not allowed" Sales units (i.e., Merchant Serial Numbers) must be especially approved to use this user flow. The merchant must have received the phone number from the customer with their consent for sending a payment request to the user's phone via the Vipps or MobilePay app. To request this feature, please contact your key account manager, your partner manager, or [customer service](https://help.vippsmobilepay.com/). ### `QR` Applicable only for `WALLET` payments. This user flow is for customer-facing screens where payments can be initiated with the [One-time payment QR](https://developer.vippsmobilepay.com/docs/APIs/qr-api/api-guide/one-time-payment.md). Example: ```bash curl -X POST https://apitest.vipps.no/epayment/v1/payments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \ -H "Merchant-Serial-Number: YOUR-MSN" \ -H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \ -H "Vipps-System-Name: acme" \ -H "Vipps-System-Version: 3.1.2" \ -H "Vipps-System-Plugin-Name: acme-webshop" \ -H "Vipps-System-Plugin-Version: 4.5.6" \ -d '{ "userFlow": "QR", "qrFormat": { "format": "IMAGE/SVG+XML", "size": 1024 }, "amount": { "value": 42924, "currency": "NOK" }, "paymentMethod": { "type": "WALLET" }, "customerInteraction": "CUSTOMER_PRESENT", "reference": 2486791679658155992, "returnUrl": "http://example.com/redirect?reference=2486791679658155992", "paymentDescription": "Ear buds" }' ``` Specify `"customerInteraction": "CUSTOMER_PRESENT"`, since the customer is present. You can also specify the order details at this time. Display the dynamic QR on a screen facing the customer. Image: A one-time payment QR code displayed on a merchant screen for a customer to scan with their Vipps or MobilePay app. When the customer scans the QR code and is directed to the Vipps or MobilePay app, the payment screen is presented and they click *Pay*. ### `NATIVE_REDIRECT` **WARNING** You are strongly encouraged to use `WEB_REDIRECT` instead. It is safer and provides fallback to the landing page in case the Vipps or MobilePay app can't be found. See [General info: App flow recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow.md). Applicable only for `WALLET` payments initiated from an app on the user's phone. Example: ```bash curl -X POST https://apitest.vipps.no/epayment/v1/payments \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \ -H "Merchant-Serial-Number: YOUR-MSN" \ -H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \ -H "Vipps-System-Name: acme" \ -H "Vipps-System-Version: 3.1.2" \ -H "Vipps-System-Plugin-Name: acme-webshop" \ -H "Vipps-System-Plugin-Version: 4.5.6" \ -d '{ "amount": { "value": 15000, "currency": "DKK" }, "paymentMethod": { "type": "WALLET" }, "customer": { "phoneNumber": "4512345678" }, "reference": 21203831704360461822, "userFlow": "NATIVE_REDIRECT" }' ``` This should cause a switch from the merchant app to the Vipps/MobilePay app and back; however, it should only be used if the merchant doesn't have a web presence at all. Please see [General info: App flow recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow.md) for more details. ## App switch integration We recommend that you use `WEB_REDIRECT` and implement universal links (starting with `https`) as they contain built-in logic to handle both desktop and mobile flow. They are more secure than the deep link flow and provide a better user experience. Please see [General info: App flow recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow.md) for more details. ## App notifications When an ePayment is created, the customer receives a push notification that approval is needed. No further notifications (push or SMS) are sent if the payment isn't approved or completed. The payment status remains visible in the app for the customer to act on at any time. ## Rate limiting We have added rate limiting to our APIs to increase the stability and security of our APIs. For details, see [Rate limits](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md#rate-limiting). ## Payment buttons The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) wraps payment initiation in a ready-made button, so you don't have to call the API and manage redirects yourself. It redirects to the payment on mobile and tablet, and can show it in a dialog on desktop. > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).