Quick start
Use the Recurring API to create charges for an agreement, get lists of charges for an agreement, cancel or refund charges, or capture reserved charges.
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 or cents.
Your first agreementβ
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 (How to find the API keys):
client_id
- Client_id for a test sales unit.client_secret
- Client_id 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.
You will also need:
mobileNumber
- The phone number for your test user.
- curl
- Postman
π₯ Do not store production keys in the Postman cloud. π₯
To prevent your sensitive data and credentials from being synced to the Postman cloud, store them in the Current Value fields of your Postman environment.
Open Postman and do the following:
-
Import the following files:
-
Select to use the imported global environment.
-
In the global environment, update only the Current Value field with your own values for the following:
client_id
client_secret
Ocp-Apim-Subscription-Key
merchantSerialNumber
mobileNumber
No additional setup needed :)
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 -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 for all other API requests in the Authorization
header as the Bearer token.
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
- Postman
Set the Idempotency-Key-Draft
value in your Postman environment.
Send request Draft Agreement - Legacy pricing
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.
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
- Postman
Send request Get Agreement
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
- Postman
Ensure that agreementId
is set to the ID of an ACTIVE agreement.
Set Idempotency-Key-Create
value.
Send request Create Charge - Direct capture
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
- Postman
Send request Get Charge
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
- Postman
Send request Cancel Charge
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
- Postman
Update the chargeId
to a charge that has been processed.
Send request Refund Charge
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
- Postman
Set agreementId
to the ID of an ACTIVE agreement
Send request Stop agreement
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β
See the Recurring API guide to read about the concepts and details.
For more examples, see the step-by-step instructions in the Recurring API Postman guide.