Skip to main content

Recurring API extended Postman guide

This is a guide for the using the Recurring API with Postman, and is an extension of the Recurring API quick start guide which shows the recommended flow in both Postman and curl.

Please note: Postman is discontinuing their offline version. Use only your test keys and delete them after testing. Ensure that your company allows for cloud use before continuing.

Prerequisites​

You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal, as described in the Getting started guide.

Set up​

Import the following files into Postman:

The Postman collection contains examples of all the various campaign types, so it's easy to see what they look like in the app.

In Postman, tweak the environment with your own values (see API keys):

  • client_id - Merchant key required for getting the access token.
  • client_secret - Merchant key required for getting the access token.
  • Ocp-Apim-Subscription-Key - Merchant subscription key.
  • merchantSerialNumber - Merchant ID.
  • mobileNumber - The phone 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 the following, you will start by sending a 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​

  1. Send request Get Access Token. This provides you with access to the API.

  2. Set Idempotency-Key-Draft value.

  3. Send the Draft Agreement - Legacy pricing request. This demonstrates how to create a simple agreement using POST:/agreements endpoint.

    Ctrl+click the link, it will take you to the 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.

  4. To get the information about an agreement, send Get Agreement. This uses GET:/agreements/{agreementId}. The variable agreementId is set by the Draft 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.

  1. Send Draft Agreement - Legacy pricing and direct capture initial 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 and chargeId are set in the environment.

  2. Set Idempotency-Key-Draft value.

  3. Send a request Get Agreement for information about this payment by using the GET:/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 as an initial payment with reserve capture. Then, you can capture the payment when you ship the phone.

  1. Send Draft Agreement - Legacy pricing and reserve initial charge.

    Ctrl+click on the link and complete the authorization.

  2. Set Idempotency-Key-Draft value.

  3. Send a request Get Agreement for information about this payment by using the GET:/agreements/{agreementId} endpoint.

  4. The agreementId and chargeId are set in the environment. Take 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.

  1. Send request Draft Agreement - Profile sharing flow.

    Provide the scope object in the POST:/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 and landing_page_url are retrieved from the response and set as variables.

  2. Once you complete the session, a unique identifier sub can be retrieved in the agreement details. Send a request Get Agreement for information about this payment by using the GET:/agreements/{agreementId} endpoint.

    In this example, sub is retrieved from the response and set as a variable.

  3. Send request Get Userinfo, from the User Info folder. This uses GET:/vipps-userinfo-api/userinfo/{sub} with the sub variable from the previous call.

Get a list of agreements​

  1. Send List Agreements to get a list of agreements by using the GET:/agreements endpoint.

    This includes a query status=ACTIVE, so it filters out other agreement states.

  2. Change or remove the query to see agreements with other states.

Update an agreement​

  1. Set agreementId to the ID of an ACTIVE agreement.

  2. Run Get Agreement to see the properties of the agreement.

  3. Run Update agreement which modifies some properties by using the PATCH:/agreements/{agreementId} endpoint.

  4. Run Get Agreement to see the updated properties.

Stop an agreement​

  1. Set agreementId to the ID of an ACTIVE agreement.

  2. Send the Stop agreement request, where the status is set to STOPPED in the body of PATCH:/agreements/{agreementId}.

  3. Run Get Agreement to see that the status is `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​

Charges for initial payments are created automatically. However, you need to create charge requests for the recurring payments.

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.

  1. Set agreementId to the ID of an ACTIVE agreement.

  2. Set Idempotency-Key-Create value.

  3. Send Create Charge - Direct capture. This uses the POST:/agreements/{agreementId}/charges endpoint.

    The chargeId variable is set for later use.

  4. Send Get Charge. This uses POST:/agreements/{agreementId}/charges/{chargeId} to get information about the charge. The status will be PENDING until the due date, when the payment is processed.

  5. If you run Get Charge again on the due date, the status should be CHARGED.

Get a list of charges for an agreement​

  1. Set agreementId to the ID of an agreement. Note, you can get a list of all your agreements with the Fetch Agreements example.

  2. Send List Charges which uses GET:/agreements/{agreementId}/charges.

    This includes a query chargeStatus=DUE and filters out other charge states.

  3. 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.

  1. Create a new charge, that we can safely cancel, by sending Create Charge - Reserve capture.

    The chargeId variable is set to this charge.

  2. Send Cancel Charge which uses DEL:/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.

  1. Set chargeId to the ID of a charge with status of CHARGED. The easiest way to test this is to run Draft Agreement - Reserve initial charge. This creates a charge that is immediately processed, and it sets the agreementId and chargeId to the corresponding values.

  2. Set Idempotency-Key-Refund value.

  3. Send Get Charge to see the change of status.

  4. Send Refund Charge which uses POST:/agreements/{agreementId}/charges/{chargeId}/refund.

  5. 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.

  1. In the environment, set agreementId and chargeId to refer to the agreement and charge. If you ran Draft Agreement - Reserve initial charge, you can use the values set by the example.

  2. Set Idempotency-Key-Capture value.

  3. Send Get Charge, to see the status of this charge.

  4. Send Capture reserved charge which uses POST:/agreements/{agreementId}/charges/{chargeId}/capture.

  5. Send Get Charge again, to see that the status is now "CHARGED".