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.
- curl
- Postman
In Postman, import the following files:
π₯ 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.
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
- Postman
Send request Get Access Token
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 .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
- Postman
Send request Create Payment - Web redirect
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"
}'
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.
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
- Postman
Send request Get payment
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
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
- Postman
Send request Get payment event log
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
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
- Postman
Send request Capture payment
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
}
}'
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
- Postman
Send request Refund payment
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
}
}'
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
- Postman
Send request Cancel payment
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
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.