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

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:

• makePaymentUrl
• POST:makePaymentUrl

Your first Payment

Step 1 - Setup

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.

Get these API key values for your sales unit:

• client_id - Merchant key is required for getting the access token.
• client_secret - Merchant key is required for getting the access token.
• Ocp-Apim-Subscription-Key-PSP - PSP subscription key is required for all requests.
• merchantSerialNumber - Created through the PSP Sign up API with POST:/merchant-management/psp/v1/merchants.

You will also need:

• PSP-ID - PSP ID provided by Vipps, needed for Initiate a PSP Payment, Update Status, and Get Details.
• mobileNumber - Test mobile number, needed only for Initiate a PSP Payment.
• makePaymentUrl - PSP provided URL used by Vipps to send the card data.
• pspRedirectUrl - Redirect URL which the user is redirected to after approving/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' \
-H 'Vipps-System-Name: YOUR-SYSTEM-NAME' \
-H 'Vipps-System-Version: YOUR-SYSTEM-VERSION' \
-H 'Vipps-System-Plugin-Name: YOUR-PLUGIN-NAME' \
-H 'Vipps-System-Plugin-Version: YOUR-PLUGIN-VERSION' \
--data ''

For an explanation of the headers, see HTTP headers.

The property access_token should be used as the Bearer token in the Authorization header of all the following API 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  <keep this secret>' \
-H 'PSP-ID: <Provided by Vipps>' \
-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 a receipt 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: <Provided by Vipps>' \
-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 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H 'PSP-ID: <Provided by Vipps>' \
-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 to read about the concepts and details.