Skip to main content

Recurring API

For full Recurring API documentation, see the Recurring API section. This page covers the PSP-specific card passthrough additions.

Since the Recurring API traditionally has not supported PSPs, some readers may not be familiar with it—and with Vipps MobilePay Recurring Payments in general. Some background context is helpful for understanding the proposed solution for extending the Recurring API to support PSPs, especially as it differs from the ePayment API in several important ways.

If you are already familiar with Vipps MobilePay Recurring Payments and the Recurring API, feel free to jump straight to the sections describing the proposed PSP flows, starting with the proposed flow for creating and signing payment agreements.

Card passthrough​

Vipps MobilePay Recurring Payments can be used for most typical Merchant-initiated transaction (MIT) payment flows, such as subscription services, pay-per-use services, and card-on-file-type solutions. In other words, it is a typical subscription product that allows merchants to charge customers a specific amount at defined intervals—without the customer having to confirm the payment each time.

The tree main entities and flows that you need to be aware of are:

  • Agreements and the agreement sign-up flow
  • Payment sources and the payment source update flow
  • Charges and the charge flow

Agreements​

The Recurring API centers around payment agreements, which function as a contract between a merchant and a user, specifying how much and how often the user may be charged.

Agreements are signed in the Vipps MobilePay app as part of the agreement sign-up flow. During this process, the user selects the payment source they want to use for the agreement, and a CIT must be performed to verify the payment source.

For direct merchants, this CIT is processed and verified by us. For PSP merchants, however, the CIT must be processed by the PSP. Our proposed solution for this is detailed further below. Once the CIT has been successfully processed, the agreement is considered signed and active, and the user can now be charged.

To learn more about agreements—including the different agreement types, how to create and update them, how they appear in the app, and more—see the Agreement section in the Recurring API guide

The main difference you need to be aware of as a PSP, compared to a direct merchant, is the CIT required to verify the payment source and confirm the agreement. As mentioned above, you will need to process this CIT and inform us of the result. This is detailed in the creating and signing agreements subsection.

Charges​

Charges are attached to agreements, and you charge a user according to the terms specified in the agreement. Charges are initiated and processed through the charge flow.

The Recurring API supports two types of charges:

  • Recurring charges: Charges with a set due date and optional retry days. These are visible in the app before the due date and processed in various batches throughout the day in each country where Vipps MobilePay operates.
  • Unscheduled charges: One-off charges without a due date that are processed as soon as possible, independent of the batches. These will be visible in the app only after being processed. Retry days are not supported.

For PSPs, only unscheduled charges will be supported initially. Based on our experiences with larger merchants and partners with strong technical teams, we trust that you want to build and control your own retry and scheduling logic—but any feedback is welcome!

In addition to the two main charge types above, an optional initial charge can be specified when drafting new agreements. If included in the request, this will be presented to the user as part of the agreement sign-up flow in the app and will be the amount used in the CIT that you must process for verifying the payment source. Note that you must always process this CIT, regardless of whether an initial charge is specified. It only controls the amount:

  • Initial charge specified -> CIT amount = initial charge amount
  • No initial charge specified -> CIT amount = 0 (zero-amount CIT)

For both direct merchants and PSPs, all charges must be initiated by the merchant through the Recurring API. We never create charges on behalf of merchants—even if the payment agreement has a specific amount and interval that states that x amount of money should be withdrawn each y period. It is always the merchant's responsibility to ensure that charges are created according to the terms specified in the payment agreement.

Since PSPs will only have access to unscheduled charges, this means that if a user has a payment agreement that specifies a monthly payment of NOK 100, your system must be configured to create a NOK 100 charge each month.

To learn more about charges—including charge types, how to create charges, how they appear in the app, and more—see the Charges section in the Recurring API guide.

Payment sources​

Each agreement has an attached payment source, chosen by the user during the agreement sign-up flow. The user can also change the payment source in the app later, after the agreement has been signed. In both cases, a zero-amount CIT is performed to verify the new payment source.

For PSP merchants, cards will be the only supported payment source initially.

To learn more about payment sources and how they are represented on agreements in the app, see: Change the payment source

For all three main flows explained above, you will get tokenized card info and will need to update us of the payment processing result. How you update us of the result will depend on the flow and whether it's a CIT or MIT. Our proposed solutions for this are detailed below.

The following sections outline how we imagine the three main Recurring flows—creating and signing agreements, payment source updates on existing agreements, and creating and processing charges—will be adapted for PSP merchants.

Creating and signing agreements​

Create new agreements by sending a POST request to the Recurring API POST:/recurring/v3/agreements endpoint and include the cardPassthrough property, as detailed below:

  • pspReference (required): Your unique reference for the agreement.
  • cardCallbackUrl (required): URL where we will send the card token.
  • allowedCardTypes: Card types the user can select. Values: VISA_DEBIT, VISA_CREDIT, VISA_DANKORT, DANKORT, MC_CREDIT, MC_DEBIT. If not specified, all types are allowed.
  • preferVisaPartOfVisaDankort: When true, prefer the Visa part of a Visa/Dankort co-branded card. Default: false.

The fields are mostly the same as for the ePayment API POST:/epayment/v1/payments endpoint, with just a minor difference in the pspReference.

As discussed in the previous section on charges the optional initial charge in the draft agreement request controls the amount in the CIT that you need to process as part of the agreement sign-up flow.

Regardless if the optional charge is specified or not, we will forward the card details to you the same way we would for an ePayment payment, and it will be your responsibility to process the CIT—a zero-amount verification CIT in the case of a missing initial charge.

A minimal draft agreement request body containing the cardPassthrough property for creating an agreement that specifies that a user should pay 100 NOK monthly with a 100 NOK initial charge might look something like this:

{
    "pricing": {
        "type": "LEGACY",
        "currency": "NOK",
        "amount": 10000
    },
    "interval": {
        "unit" : "MONTH",
        "count": "1"
    },
    "initialCharge": {
      "amount": 10000,
      "description": "First payment",
      "transactionType": "DIRECT_CAPTURE"
    },
    "merchantRedirectUrl": "https://example.com/redirect",
    "merchantAgreementUrl": "https://example.com/agreement",
    "productName": "Streaming subscription",
    "cardPassthrough": {            
      "pspReference": "subscription-product-123",
      "cardCallbackUrl": "https://example.com/psp-makepayment",
      "allowedCardTypes": [ "VISA_DEBIT", "VISA_CREDIT", "VISA_DANKORT", "MC_CREDIT", "MC_DEBIT"],
      "preferVisaPartOfVisaDankort": true,
      "publicEncryptionKeyId": "some-guid"
    }
}

The sequence diagram below shows the proposed flow for creating and signing new agreements:

From your perspective, this will be very similar to the payments flow in the ePayment API—and the payment source update flow detailed below. In all three cases, a CIT is performed and you get a card info callback from us that you need to reply to synchronously within the 20 second timeout window, as explained in detail in the ePayment API card callback subsection.

Once the agreement is successfully signed, you are ready to charge the user according to the terms specified in the agreement.

Please note that it's also possible for the user to explicitly reject the agreement or for an agreement to expire (if the user abandons the flow) as part of the sign-up flow. You can be notified of this and other events by integrating with our webhooks service. To learn more about all the possible agreement events you can be notified of, please refer to the relevant section in our documentation about agreement webhooks.

Payment source updates​

Each agreement has an attached payment source that can be changed by the user in the app at any time. When the user changes the payment source on an agreement, the new payment source needs to be verified. This is done by performing a zero-amount verification transaction. In the case of PSP agreements, it is your responsibility to process this transaction.

The payment source update flow is very similar to the agreement sign-up flow explained earlier. In both cases, a CIT is performed where you get a card info callback that you need to respond to synchronously to inform us of the processing result. The main difference in the case of a payment source update, is that it's fully initiated by the user.

Please note the previously discussed similarity to the agreement sign-up and ePayment payment flow, where you need to listen to a card callback, process the payment, and respond within the 20 second timeout window.

Creating charges​

Compared to the above-mentioned ePayment payment flow and the Recurring agreement signing and payment-source update flows—where you need to listen for an async callback to get the card info, process the payment, and respond synchronously—we have designed and propose a new flow for Recurring charges that combine synchronous charge creation with asynchronous payment processing and updates.

Create a new charge by sending a POST request to either of the Recurring API charge creation endpoints:

The sequence diagram below shows the proposed flow single charges:

The sequence diagram below shows the proposed flow for batch charges:

Note that in both cases the card info is returned directly in the initial charge creation request. There is therefore no need for the cardPassthrough object property to be included in the charge creation request.

Compared to the card callback flow used for the CIT-based flows explained previously—where you need to respond to the card info callback within 20 seconds synchronously, and we perform some action based on that—for the proposed Recurring charge processing flow, we will introduce a new PSP-specific charge update endpoint where you need to inform us of the payment processing result asynchronously.

It is very important that you inform us of this charge update, or else the charge will remain in an unresolved state in our system and therefore also in the app—leading to a suboptimal user experience and potential support requests.

Card callback​

When the user confirms an agreement or change or payment method in the Vipps MobilePay app and selects their card, we send a POST request to your cardCallbackUrl with the card token. You must respond synchronously with the payment status within 20 seconds.

See card callback for details.

Last updated on