Quick start

Only available for Vipps.

Use the PSP API to initiate a PSP payment and get details or update the status of this payment.

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

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 - Required only for Get Merchant by MSN.

See How to find the API keys.

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 URL used by Vipps to send the card data.
• pspRedirectUrl - Redirect URL which the user is redirected to after approving/rejecting the payment.

Note that the requests in this PSP API require your PSP subscription key.

Step 2 - Authentication

For all the following, you will need an access_token from: POST:/accesstoken/get.

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 property access_token should be used for all other API requests in the Authorization header as the Bearer token.

Step 3 - A simple payment

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

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-SUBSCRIPTION-KEY  <This is the PSP's key, and is the same for all the PSP's merchants. Keep it 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' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \
-d '{
  "pspTransactionId": "428FY3Zmeyc",
  "merchantOrderId": "8WG39VI9hywg",
  "customerMobileNumber": "96574209",
  "amount": "49900",
  "currency": "NOK",
  "pspRedirectUrl": "https://example.com",
  "makePaymentUrl": "https://example.com",
  "makePaymentToken": "WCAG6W5HYWGg4",
  "paymentText": "Transaction initiated.",
  "isApp": false,
  "skipLandingPage": false
}'

Step 4 - Completing the payment

Ctrl+click (Command-click on macOS) on the link that appears, 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 or reject the payment. Once you have acted upon the payment, you will be redirected back to the specified pspRedirectUrl URL 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 - Getting the status of the payment

To see the details about the transaction, run 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" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

Step 6 (Optional): Update the payment

You can update the payment with the POST:/psp/v3/psppayments/updatestatus endpoint.

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" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "transactions": [
   {
      "pspTransactionId": "428FY3Zmeyc",
      "status": "CAPTURED",
      "amount": "49900",
      "currency": "NOK",
      "paymentText": "Transaction updated"
   }
  ]
}'

Next steps

See the PSP API guide to read about the concepts and details.