Subscriptions to Recurring
Below, you can find comparison between the existing MobilePay Subscriptions API and the new Recurring API replacing MobilePay Subscriptions.
Stay Updated
- NEW Recurring Changelogs: All notable changes to the Recurring API.
API documentation:
If you didn't make the integration yourself, talk with your partner.
Authentication and management
We will have a joint authentication solution across our API platform and introduce a Management API to retrieve merchant data. Read more here.
Agreement
See: Agreements
| MobilePay Agreement | Vipps MobilePay Agreement |
|---|---|
Description | productDescription |
Amount | pricing: { "type"("LEGACY" => amount ,"VARIABLE" => suggestedMaxAmount), "currency"("NOK") } |
Frequency | interval: { "unit"("YEAR" "MONTH" "WEEK" "DAY"), "count"([1..31]) } |
Links: [user-redirect, success-callback, cancel-callback, cancel-redirect] | merchantRedirectUrl + merchantAgreementUrl |
Plan | productName |
mobile_phone_number | phoneNumber |
external_id | externalId |
currency | N/A |
country_code | N/A |
expiration_timeout_minutes | N/A |
retention_period_hours | N/A |
disable_notification_management | N/A |
notifications_on | N/A |
| N/A | scope (Space-separated list of the user profile-data scope to require for the agreement) |
| N/A | isApp (If merchant is redirecting user from an app or a mobile device) |
| N/A | skipLandingPage (true = skip landing page by sending a push notification directly to the user) |
Charges
See: Charges
| MobilePay one-off | Vipps MobilePay initial charge |
|---|---|
Amount (kroner.øre) | amount (øre) |
External_id | orderId (if NULL → autogenerated. See Recommendations for reference and orderId.) |
Description | description |
Expiration_timeout_minutes | N/A |
| N/A | transactionType (RESERVE_CAPTURE, DIRECT_CAPTURE) |
| MOBILEPAY RESPONSE FROM AGREEMENT | VIPPS MOBILEPAY RESPONSE FROM AGREEMENT |
Id | agreementId |
links["rel", "href"] | vippsConfirmationUrl |
one_off_payment_id | chargeId |
Refunds & Captures
Refunds and captures for payments and one off payments made before Nordic Wallet Launch must be handled by utilizing the OLD Subscriptions API.
Callbacks
If you are planning to reintegrate, you will have to start using new callback (webhook) solution. By default, even after reintegration you will receive webhooks in the old MobilePay format, but there is no possibility to change callback URL or authentication method. It is important to notice that after integrating towards new webhook solution you will be receiving both new and old webhooks. You have to notify us about integration to webhooks, in order for us to turn of old MobilePay callbacks for you.
These are the available fields of payment webhook we will be sending
| Field name | Type | Description | Possible values |
|---|---|---|---|
| agreementId | string | ID of an agreement | "agr_kFW4chk" |
| chargeExternalId | nullable string | Merchant provided external ID of payment | "ExtId123" |
| chargeId | string | ID of payment | "82ce990f-d08a-448c-bd26-ee6be8418d06" |
| amount | number | Amount of payment in cents | 300 |
| chargeType | enum | Indicates if it is recurring, or agreement's initial one off payment | "RECURRING", "INITIAL" |
| eventType | enum | Indicates what has happened to a charge | Values provided in a table below |
| currency | enum | Currency of payment | "DKK", "NOK", "EUR" |
| occurred | ISO 8601 UTC date | When change has occurred | 2023-10-10T13:30:36.079765975Z |
| amountCaptured | number | Amount of payment that was captured | 100 |
| amountCanceled | number | Amount of payment that was canceled | 200 |
| amountRefunded | number | Amount of payment that was refunded | 100 |
These are the possible event types in payment callback
| Event type | Description |
|---|---|
| "recurring.charge-reserved.v1" | Payment was reserved. Event is not sent for recurring payments with transaction type "DIRECT_CAPTURE" |
| "recurring.charge-captured.v1" | Payment was fully or partially captured |
| "recurring.charge-canceled.v1" | Payment was fully or partially cancelled |
| "recurring.charge-failed.v1" | Payment failed and will no longer be retried |
| "recurring.charge-creation-failed.v1" | Payment failed to be created. Sent when merchants are using charge batch creation endpoint and charges are created asynchronously |
This is an example of new payment callback
{
"agreementId": "agr_kFW4chk",
"chargeExternalId": "extId",
"chargeId": "82ce990f-d08a-448c-bd26-ee6be8418d06",
"amount": 300,
"chargeType": "RECURRING",
"eventType": "recurring.charge-canceled.v1",
"currency": "NOK",
"occurred": "2023-10-10T13:30:36.079765975Z",
"amountCaptured": 0,
"amountCanceled": 300,
"amountRefunded": 0
}
These are the available fields of agreement webhook we will be sending
| Field name | Type | Description | Possible values |
|---|---|---|---|
| agreementId | string | Id of an agreement | "agr_kFW4chk" |
| agreementUUID | UUID | Id of an agreement | "82ce990f-d08a-448c-bd26-ee6be8418d06" |
| agreementExternalId | nullable string | Merchant provided externalId of agreement | "ExtId123" |
| eventType | enum | Indicates what has happened to an agreement | Values provided in a table below |
| occurred | ISO 8601 UTC date | When change has occurred | 2023-10-10T13:30:36.079765975Z |
| actor | nullable enum | Indicates who has initiated action. Applicable only for agreementStopped webhook | "MERCHANT", "USER" |
These are the possible event types in agreement callback
| Event type | Description |
|---|---|
| "recurring.agreement-activated.v1" | User has accepted agreement |
| "recurring.agreement-rejected.v1" | User has rejected agreement |
| "recurring.agreement-stopped.v1" | Agreement was stopped either by merchant either by user |
| "recurring.agreement-expired.v1" | Agreement has expired |
This is an example of the new agreement callback:
{
"agreementId": "agr_hXbXJUN",
"occurred": "2023-10-11T09:51:04.562829303Z",
"agreementExternalId": null,
"eventType": "recurring.agreement-expired.v1",
"agreementUUID": "c81bf516-7972-488e-bbf1-146dcd8592f9",
"actor": null
}
{
"agreementId": "agr_hXbXJUN",
"occurred": "2023-10-11T09:51:04.562829303Z",
"agreementExternalId": null,
"eventType": "recurring.agreement-stopped.v1",
"agreementUUID": "c81bf516-7972-488e-bbf1-146dcd8592f9",
"actor": "MERCHANT"
}
Test environment
The test environment is called Merchant Test (MT) and is now open for test. MT currently only allows Norwegian phone numbers, currency and merchants, but you can test the API and payment flow. Please see the details of limitations of the test environment.
Management API and Report API is not available in MT and can only be tested in production.
In order to request access to the test environment, please use the following links:
We will e-mail you with the information you need to get started. This is also needed even though you are an existing MobilePay integrator or merchant, since we need your information registered on our new joint platform.