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.

info

The minimum amount in NOK and DKK is 100 øre. The minimum amount in EUR is 1 cent.

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. See Getting started guide for help.

Get these API key values for your sales unit:

• 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.

See How to find the API keys.

You will also need:

• internationalMobileNumber - The MSISDN for the test app profile you have received or registered. This is your test mobile number including country code.

curl

In Postman, import the following files:

• ePayment API Postman collection
• Global Postman environment

🔥 To reduce risk of exposure, never store production keys in Postman or any similar tools. 🔥

Update the Current Value field in your Postman environment with your Merchant Test keys. Use Current Value field for added security, as these values are not synced to the cloud.

Postman

No additional setup needed :)

Install the .NET SDK to your project

dotnet add package vipps.net

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

Send request Get Access Token

Postman

curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-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' \
--data ''

Replace the value of the Vipps-System headers with your own values. See HTTP headers for more details.

note

When a partner uses partner keys for requests that are not for a specific merchant, the Merchant-Serial-Number can be omitted.

The .NET SDK will handle access token fetching for you, all you need to do is to add the following configuration code

var vippsConfigurationOptions = new VippsConfigurationOptions
{
    ClientId = YOUR-CLIENT-ID,
    ClientSecret = YOUR-CLIENT-SECRET,
    MerchantSerialNumber = YOUR-MERCHANT-SERIAL-NUMBER,
    SubscriptionKey = YOUR-SUBSCRIPTION-KEY,
    UseTestMode = true // TODO?
};

VippsConfiguration.ConfigureVipps(vippsConfigurationOptions);

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:/epayment/v1/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 prefilled in the form.

curl

Send request Create Payment - Web redirect

Postman

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": 1000
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "4712345678"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.come/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'

var reference = Guid.NewGuid().ToString();
var customerPhoneNumber = "4712345678";
var createPaymentRequest = new CreatePaymentRequest
    {
        Amount = new Amount
        {
            Currency = Currency.NOK,
            Value = 1000 // 1000 øre = 10 KR
        },
        PaymentMethod = new PaymentMethod { Type = PaymentMethodType.WALLET },
        UserFlow = CreatePaymentRequestUserFlow.WEB_REDIRECT,
        Reference = reference,
        PaymentDescription = "Two pairs of socks and one coffee",
        ReturnUrl = $"https://no.where.com/{reference}",
        Customer = new Customer { PhoneNumber = customerPhoneNumber }
    };
var createPaymentResult = await EpaymentService.CreatePayment(createPaymentRequest);

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:/epayment/v1/payments/{reference}.

curl

Send request Get payment

Postman

curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE \
-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 "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" \

var payment = await EpaymentService.GetPayment(reference);

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:/epayment/v1/payments/{reference}/events endpoint.

curl

Send request Get payment event log

Postman

curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/events \
-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 "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" \

var paymentEventLog = await EpaymentService.GetPaymentEventLog(reference);

Step 6 - Capture the payment

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

curl

Send request Capture payment

Postman

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-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 '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 1000
  }
}'

var captureAmount = new Amount() { Value = 1000, Currency = Currency.NOK };
var captureResult = await EpaymentService.CapturePayment(
reference,
new CaptureModificationRequest { ModificationAmount = captureAmount });

See Knowledge base: Reserve and capture for more details about the types of captures.

Step 7 - Refund the payment

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

curl

Send request Refund payment

Postman

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-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 '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 1000
  }
}'

var refundAmount = new Amount() { Value = 1000, Currency = Currency.NOK };
var refundResult = await EpaymentService.RefundPayment(
reference,
new RefundModificationRequest { ModificationAmount = refundAmount });

See Knowledge base: refund for more details about refunds.

Step 8 - Cancel the payment

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

curl

Send request Cancel payment

Postman

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-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" \

var cancelResult = await EpaymentService.CancelPayment(reference);

See Knowledge base: 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.

• Capture the payment
• Payment modification, how to use cancel, capture and refund?
• Using ePayment API in a shopper present context
• Profile sharing, requesting the users personal information