Quick start

This guide takes you through all the Recurring API requests.

Before you begin

Sign up as an organization with Vipps MobilePay and get your API keys:

• client_id - Client_id for a test sales unit.
• client_secret - Client secret for a test sales unit.
• Ocp-Apim-Subscription-Key - The subscription key for making API requests.
• merchantSerialNumber - The unique ID for a test sales unit.

If you're new to the platform, see Getting started for information about API keys, product activation, and the test environment.

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.

Your first agreement

Step 1 - Setup

If using Postman, download the following files and import them into Postman. Select the global environment as your active environment and update the Current Value field with your own values for the API keys and mobile number. 🔥 Do not store production keys in the cloud. 🔥

• Download Recurring API Postman collection
• Download Global Postman environment

Step 2 - Get an access token

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

For production, include all the Vipps-System headers so that we can help with debugging any problems. For details, 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 - Create a minimal agreement

Create an agreement with: POST:/recurring/v3/agreements. When your test mobile number is provided in phoneNumber, it will be prefilled in the form.

Note that orderId must be unique for each payment you create.

curl

Set the Idempotency-Key-Draft value in your Postman environment.

Send request "Draft Agreement - Legacy pricing"

Postman

curl -X POST https://apitest.vipps.no/recurring/v3/agreements/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-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 '{
   "interval": {
      "unit" : "WEEK",
      "count": 2
   },
   "pricing": {
      "amount": 1000,
      "currency": "NOK"
   },
   "merchantRedirectUrl": "https://example.com/redirect-url",
   "merchantAgreementUrl": "https://example.com/agreement-url",
   "phoneNumber": "12345678",
   "productName": "Test product"
}'

Step 4 - Authorize the agreement

Open the vippsConfirmationUrl link that is returned in the previous step. 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 agreement in the app, where you can authorize and be directed to the specified merchantRedirectUrl 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.

You should now have an active agreement. Take note of the value included in agreementId, as you will need this to access the agreement later.

Step 5 - Fetch the agreement

To receive the result of the user action, you may poll the status of the agreement with: GET:/recurring/v3/agreements/{agreementId}.

curl

Send request "Get Agreement"

Postman

curl -X GET https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-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" \

If you confirmed the agreement, the status should be ACTIVE in the response.

Step 6 - Create a charge for the agreement

Create a charge with: POST:/recurring/v3/agreements/{agreementId}/charges.

Set a unique orderId that can be used to access the charge later. Also, set a unique Idempotency-Key value to ensure the charge is not created more than once.

curl

Ensure that agreementId is set to the ID of an ACTIVE agreement.

Set Idempotency-Key-Create value.

Send request "Create Charge - Direct capture"

Postman

curl -X POST https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID/charges \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-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 '{
  "amount": 1000,
  "description": "This payment was charged with Postman.",
  "due": "2023-08-08",
  "retryDays": 0,
  "transactionType": "DIRECT_CAPTURE",
  "orderId": "UNIQUE-ORDERID"
}'

The status will be PENDING until the payment is processed.

A charge must be scheduled a minimum of two days before the payment will occur (it is a minimum one day in the test environment). See Direct Capture for more details about timing.

Step 7 - Fetch the charge

To get the status of the charge, use: POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}.

The value for chargeId must match what you provided for orderId.

curl

Send request "Get Charge"

Postman

curl -X GET https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID/charges/UNIQUE-ORDERID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-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" \

(Optional) Step 8 - Cancel the charge

To cancel an unpaid charge, use: DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId}.

curl

Send request "Cancel Charge"

Postman

curl -X DELETE https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID/charges/UNIQUE-CHARGE-ID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-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" \

(Optional) Step 9 - Refund a charge

To refund a charge, use: POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/refund.

curl

Update the chargeId to a charge that has been processed.

Send request "Refund Charge"

Postman

curl -X POST https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID/charges/UNIQUE-CHARGE-ID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-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 '{
  "amount": 1000,
  "description":"This charge was refunded with Postman"
}'

(Optional) Step 10 - Stop an agreement

To stop an agreement, send PATCH:/recurring/v3/agreements/{agreementId} with "status": "STOPPED".

curl

Set agreementId to the ID of an ACTIVE agreement

Send request "Stop agreement"

Postman

curl -X PATCH https://apitest.vipps.no/recurring/v3/agreements/UNIQUE-AGREEMENT-ID  \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-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 '{
  "status": "STOPPED"
}'

Next steps

Complete the required Recurring checklist to integrate the API into your software.