Skip to main content

Quick start

Before you begin​

The provided example values in this guide must be changed with the values for your sales unit and user. This applies for API keys, HTTP headers, reference, phone number, etc. Note that any currency amount must be an Integer value minimum 100 in ΓΈre.

Your first Payment​

Step 1 - Setup​

You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal.

You will need the following values, as described in the Getting started guide:

  • client_id - Client_id for a test sales unit.
  • client_secret - Client_id for a test sales unit.
  • Ocp-Apim-Subscription-Key - Subscription key for a test sales unit.
  • merchantSerialNumber - The unique ID for a test sales unit.
  • internationalMobileNumber - The MSISDN for the test app profile you have received or registered. This is your test mobile number including country code.

No additional setup needed :)

Step 2 - Authentication​

For all the following, you will need an access_token from the Access token API: POST:/accesstoken/get. This provides you with access to the API.

curl https://apitest.vipps.no/accessToken/get \
-H "client_id: YOUR-CLIENT-ID" \
-H "client_secret: YOUR-CLIENT-SECRET" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-X POST \
--data ''

The property access_token should be used for all other API requests in the Authorization header as the Bearer token.

Step 3 - Request a simple payment​

Initiate a payment with: POST:/payments. In this example, we use the default user flow, WEB_REDIRECT. This provides you with a link you can click to go to the landing page. When your test mobile number (in MSISDN format) is provided in phoneNumber, it will be pre-filled in the form.

curl https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-H "Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
"amount": {
"currency": "NOK",
"value": 1000
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"phoneNumber": "4791234567"
},
"reference": "acme-shop-123-order123abc",
"returnUrl": "https://yourwebsite.come/redirect?reference=abcc123",
"userFlow": "WEB_REDIRECT",
"paymentDescription": "One pair of socks"
}'

Step 4 - Complete the payment​

Open the redirectUrl link that is returned, and it will take you to the landing page. The phone number of your test user should already be filled in, so you only have to click Next.

You will be presented with the payment in the app, where you can complete the payment and be directed to the specified returnUrl under a "best effort" policy.

note

We cannot guarantee the user will be redirected back to the same browser or session, or that they will at all be redirected back. User interaction can be unpredictable, and the user may choose to fully close the app or browser.

Step 5 - Get the status of the payment​

To receive the result of the user action, you may poll the status of the payment via the GET:/payments/{reference}.

curl https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-X GET

To verify that a payment has been authorized by the user, check that the state property is marked AUTHORIZED. If the user has instead chosen to reject the payment or chosen to click cancel on the landing page or in the app, the state property will be marked ABORTED. If the user did not act within the payment expiration time, the state property will be marked EXPIRED.

For more details of the lifecycle of the payment session the GET:/payments/{reference}/events endpoint.

curl https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-X GET

Step 6 - Capture the payment​

After the goods or services have been delivered, you can capture the authorized amount either partially or fully: POST:/payments/{reference}/capture.

curl https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-H "Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
"modificationAmount": {
"currency": "NOK",
"value": 1000
}
}'

See Common topics: Capture for more details about the types of captures.

(Optional) Step 7 - Refund the payment​

To refund the captured amount, either partially or fully: POST:/payments/{reference}/refund.

curl https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-H "Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
"modificationAmount": {
"currency": "NOK",
"value": 1000
}
}'

See Common topics: refund for more details about refunds.

(Optional) Step 8 - Cancel the payment​

To cancel the payment, either fully or after a partial capture: POST:/payments/{reference}/cancel.

curl https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-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" \
-H "Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST

See Common topics: Cancel for more details about cancel.

Next Steps​

Now that you have completed your first payment, read further to see the full range of possibilities within the ePayment API.

Help us improve our documentation

Did you find what you were looking for?