Skip to main content

Vipps PSP API quick start

As a Payment Service Provider, you can use the PSP API to initiate a PSP payment and get details or update the status of this payment.

Prerequisites​

important

If you're interested in using this API, you'll need to reach out to us first. Simply fill out the PSP partner form before diving into your implementation.

Test sales unit​

You must be a Payment Service Provider (PSP) partner with Vipps MobilePay. You will receive an email with your test credentials from our partner team.

The PSP API is available for testing in the Test environment.

Service endpoint​

You must expose an endpoint where Vipps can post the network token.

Once the Vipps user has confirmed the payment in the Vipps app, Vipps shares the network token with the PSP by posting to the POST:makePaymentUrl, where makePaymentUrl is the service endpoint you have provided.

For details, see:

Your first Payment​

Step 1 - Setup​

The example values in this guide must be replaced with your own values. This applies to API keys, HTTP headers, references, phone numbers, and similar values. Note that any currency amount must be an Integer value minimum 100 in øre.

Get these API credentials for your PSP account:

  • client_id - Client ID, required for getting the access token.
  • client_secret - Client secret, required for getting the access token.
  • Ocp-Apim-Subscription-Key-PSP - PSP subscription key, required for all requests.
  • PSP-ID - Your PSP ID, provided by Vipps MobilePay. Required for all requests.

You will also need the following values per payment:

  • merchantSerialNumber - The MSN of the merchant you are processing payments for. Each merchant you onboard via the PSP Signup API gets their own MSN.
  • mobileNumber - The customer's mobile number, needed only for Initiate a PSP Payment.
  • makePaymentUrl - PSP-provided URL where Vipps sends the card token after the customer approves payment.
  • pspRedirectUrl - URL the customer is redirected to after approving or rejecting the payment.

Step 2 - Get an access token​

Get an access token by sending the POST:/accesstoken/get request.

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' \
--data ''

In production, include all Vipps-System headers to aid debugging. See HTTP headers for details.

Use the access_token value as the Bearer token in the Authorization header of all subsequent requests.

Step 3 - Initiate the payment​

Initiate a payment with: POST:/psp/v3/psppayments/init/. For example:

curl -X POST "https://apitest.vipps.no/psp/v3/psppayments/init" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-PSP-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-d '{
  "pspTransactionId": "abcABC12345",
  "merchantOrderId": "abcABC-12345",
  "customerMobileNumber": "12345678",
  "amount": "49900",
  "currency": "NOK",
  "pspRedirectUrl": "https://example.com/page-seen-after-payment",
  "makePaymentUrl": "https://example.com/your-endpoint-for-card-data",
  "makePaymentToken": "YOUR-AUTHORIZATION-HEADER-FOR-makePaymentUrl-optional",
  "paymentText": "OrderId abcABC-12345 from example.com."
}'

You should get a link in the response. Paste the link into the browser to open the Vipps landing page. The phone number of your test user should already be filled in, so you only have to click Next.

A push notification will be presented in the Vipps app on your phone.

When you approve the payment, Vipps automatically reserves the payment and provides confirmation of the successful payment.

Step 4 - Show the order confirmation​

You should be redirected back to the specified pspRedirectUrl URL under a "best effort" policy. On that page, show the order confirmation.

Step 5 - Receive the user's card token​

When the payment is confirmed in the Vipps app, Vipps will try to share the user's card token with you by posting to the POST:makePaymentUrl.

Step 6 - Process the payment with the card token​

After receiving the card data, you can use the card token to process the payment through the acquirer.

Vipps is not involved in the actual payment, Vipps only provides the PSP with the card token.

Step 7 - Update the status of the payment in Vipps​

Update the status of the payment by sending the POST:/psp/v3/psppayments/updatestatus request. For example:

curl -X POST https://apitest.vipps.no/psp/v3/psppayments/updateStatus \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-d '{
  "transactions": [
   {
      "pspTransactionId": "abcABC12345",
      "status": "CAPTURED",
      "amount": "49900",
      "currency": "NOK",
      "paymentText": "Transaction updated"
   }
  ]
}'

Step 8 - Get the details of a payment​

To see the details about a transaction, send the GET:/psp/v3/psppayments/{pspTransactionId}/details request.

curl -X GET https://apitest.vipps.no/psp/v3/psppayments/{pspTransactionId}/details \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \

Example response:

{
"pspTransactionId": "abcABC12345",
"merchantOrderId": "abcABC-12345",
"transactionSummary": {
  "capturedAmount": 49900,
  "remainingAmountToCapture": 0,
  "refundedAmount": 0,
  "remainingAmountToRefund": 49900
},
"transactionLogHistory": [
   {}
  ]
}

Next steps​

See the PSP API guide for concepts and details.

Last updated on