Quick start

Before you begin

This document covers the quick steps for getting started with the ePayment API. You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal, as described in the Getting started guide.

Important: The examples use standard example values that you must change to use your values. This includes API keys, HTTP headers, reference, etc.

Your first Payment

Step 1 - Setup

curl

Please note: Postman is discontinuing their offline version. Use only your test keys and delete them after testing. Ensure that your company allows for cloud use before continuing.

If you wish to use Postman, import the following files:

• ePayment API Postman collection
• Global Postman environment

In Postman, tweak the environment with your own values (see API keys):

• client_id - Merchant key required for getting the access token.
• client_secret - Merchant key required for getting the access token.
• Ocp-Apim-Subscription-Key - Merchant subscription key.
• merchantSerialNumber - Merchant ID.
• internationalMobileNumber - The MSISDN for the test app profile you have received or registered. This is your test mobile number including country code.

Postman

No 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 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: 123456" \
-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 .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:/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

Send request Create Payment - Web redirect

Postman

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: 123456" \
-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"
}'

var reference = Guid.NewGuid().ToString();
var customerPhoneNumber = "4791234567";
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:/payments/{reference}.

curl

Send request Get payment

Postman

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: 123456" \
-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

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

curl

Send request Get payment event log

Postman

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: 123456" \
-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

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

curl

Send request Capture payment

Postman

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: 123456" \
-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
  }
}'

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

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

Send request Refund payment

Postman

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: 123456" \
-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
  }
}'

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

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

Send request Cancel payment

Postman

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: 123456" \
-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

var cancelResult = await EpaymentService.CancelPayment(reference);

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.

• 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