Quick start
Use the Recurring API to create different types of agreements, get information about agreements, update and stop agreements. After creating the agreements, you still need to send the charge requests. So, you 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.
Postman
Prerequisites
Review quick start guides for information about getting your test environment set up.
Step 1: Get the Postman collection and environment
Save the following files to your computer:
The Postman collection contains examples of all the various campaign types, so it's easy to see what they look like in the app.
Step 2: Import the Postman files
- In Postman, click Import in the upper-left corner.
- In the dialog that opens, with File selected, click Upload Files.
- Select the two files you have just downloaded and click Import.
Step 3: Setup Postman environment
- Click the down arrow, next to the "eye" icon in the top-right corner, and select the environment you have imported.
- Click the "eye" icon and, in the dropdown window, click
Edit
in the top-right corner. - Fill in the
Current Value
for the following fields to get started. For the first keys, go to Vipps MobilePay Portal > Utvikler -> Test Keys.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
- Merchant subscription key.merchantSerialNumber
- Merchant id.mobileNumber
- The mobile number for the test app profile you have received or registered.
You can update any of the other environment variables. Be aware of this:
- Any currency amount must be an Integer value minimum 100 in øre.
- Many URLs must be
https
.
Make API calls
For all of the following, you will start by sending request Get Access Token
.
This provides you with access to the API.
The access token is valid for 1 hour in the test environment and 24 hours in the production environment. See the API reference for details about the calls.
Create agreements
For details about the calls, see Agreement endpoints in the Recurring API Specifications.
Create a minimal agreement
Send request
Get Access Token
. This provides you with access to the API.Set
Idempotency-Key-Draft
value.Send the
Draft Agreement - Minimal
request. This demonstrates how to create a simple agreement usingPOST:/agreements
endpoint.Ctrl+click the link, it will take you to the Vipps MobilePay landing page. Enter your test phone number and complete the authorization in the Vipps or MobilePay app in your mobile test app.
You should now have an active agreement. The variable
agreementId
is set in the environment.To get the information about an agreement, send
Get Agreement
. This usesGET:/agreements/{{agreementId}}
. The variableagreementId
is set by theDraft Agreement
step.If you confirmed the agreement, the status should be ACTIVE in the response. If you didn't go through with the confirmation, the status will be PENDING for a maximum of 10 minutes, before it goes to
EXPIRED
.
Create an agreement with an initial charge
You can create more complex types of agreements by modifying the parameters in POST:/agreements
endpoint.
Send
Draft Agreement - Direct Charge
. This demonstrates the addition of an initial charge.Ctrl+click on the link and complete the authorization.
When you use this, a charge is automatically created for the initial payment and charged. The
agreementId
andchargeId
are set in the environment.Set
Idempotency-Key-Draft
value.Send request
Get Agreement
for information about this payment by using theGET:/agreements/{{agreementId}}
endpoint.
Create an agreement with a reserve capture
When you use this, a charge is automatically created for the initial payment, and you can capture it when you provide the product or service.
For example, if a customer purchased a mobile phone with a data subscription, you could set up a recurring payment agreement where the price of the phone is registered an initial payment with reserve capture. Then, you can capture the payment when you ship the phone.
Send
Draft Agreement - Reserve Charge
.Ctrl+click on the link and complete the authorization.
Set
Idempotency-Key-Draft
value.Send request
Get Agreement
for information about this payment by using theGET:/agreements/{{agreementId}}
endpoint.The
agreementId
andchargeId
are set in the environment. Take a note of these values, because you will need them when you capture the reserved charge.
Getting access to user info
If you need to get access to some user information in addition to the recurring payment agreement, you can use the profile flow.
Send request
Draft Agreement - Profile flow
.Provide the
scope
object in thePOST:/agreements
call. This contains the information types that you want access to, separated by spaces (e.g., "name address email phoneNumber birthDate").Here, the
agreementId
andlanding_page_url
are retrieved from the response and set as variables.Once you complete the session, a unique identifier
sub
can be retrieved in the agreement details. Send requestGet Agreement
for information about this payment by using theGET:/agreements/{{agreementId}}
endpoint.In this example,
sub
is retrieved from the response and set as a variable.Send request
Get Userinfo
, from the User Info folder. This usesGET:/vipps-userinfo-api/userinfo/{sub}
with thesub
variable from the previous call.
Get a list of agreements
Send
Fetch Agreements
to get a list of agreements by using theGET:/agreements
endpoint.This includes a query
status=ACTIVE
, so it filters out other agreement states.Change or remove the query to see agreements with other states.
Update an agreement
Set
agreementId
to the id of an ACTIVE agreement.Run
Get Agreement
to see the properties of the agreement.Run
Update agreement
which modifies some properties by using thePATCH:/agreements/{{agreementId}}
endpoint.Run
Get Agreement
to see the updated properties.
Stop an agreement
Set
agreementId
to the id of an ACTIVE agreement.Send the
Stop agreement
request, where the status is set toSTOPPED
in the body ofPATCH:/agreements/{{agreementId}}
.Run
Get Agreement
to see that the status is not "STOPPED".
Create charges
You will need at least one ACTIVE agreement for these examples.
For details about the calls, see Charge endpoints in the Recurring API Specifications.
Create a charge
Although charges for initial payments are created automatically, you must create charge requests for the recurring payments.
A charge must be scheduled a minimum of two days before the payment will occur (it is minimum one day in the test environment). See Direct Capture for more details about timing.
Set
agreementId
to the id of an ACTIVE agreement.Set
Idempotency-Key-Create
value.Send
Create Charge - Due tomorrow
. This uses thecreate charge
endpoint with "due" set to tomorrow's date.The
chargeId
variable is set for later use.Send
Get Charge
. This usesPOST:/agreements/{{agreementId}}/charges
to get information about the charge. The status will be "PENDING" for a while before it goes to "DUE".If you run
Get Charge
again tomorrow, you should see that the status changes to "CHARGED".
Get a list of charges for an agreement
Set
agreementId
to the id of an agreement. Note, you can get a list of all your agreements with theFetch Agreements
example.Send
List Charges
which usesGET:/agreements/{{agreementId}}/charges
.This includes a query
chargeStatus=DUE
and filters out other charge states.Change or remove the query to see charges with other states.
Cancel a charge
You can cancel an existing charge before the user is charged.
Create a new charge, that we can safely cancel, by sending
Create Charge - Due tomorrow
.The
chargeId
variable is set to this charge.Send
Cancel Charge
which usesDEL:/agreements/{{agreementId}}/charges/{{chargeId}}
.Send
Get Charge
to see the change of status.
Refund a charge
You can refund a charge that has already been charged.
Set
chargeId
to the id of a charge with status of CHARGED. The easiest way to test this is to runDraft Agreement - Full
. This creates a charge that is immediately processed, and it sets theagreementId
andchargeId
to the corresponding values.Set
Idempotency-Key-Refund
value.Send
Get Charge
to see the change of status.Send
Refund Charge
which usesPOST:/agreements/{{agreementId}}/charges/{{chargeId}}/refund
.Send
Get Charge
to see that the charge is all or partially refunded. To fully refund, set the amount value to the amount remaining (amount - amountRefunded).
Capture reserved charge
When you create an agreement with a reserved charge, you will need to capture this charge.
In the environment, set
agreementId
andchargeId
to refer to the agreement and charge. If you ran Create an agreement with a reserve capture, you can use the values set by the example.Set
Idempotency-Key-Capture
value.Send
Get Charge
, to see the status of this charge.Send
Capture reserved charge
which usesPOST:/agreements/{{agreementId}}/charges/{{chargeId}}/capture
.Send
Get Charge
again, to see that the status is now "CHARGED".