Skip to main content
API docs by Redocly

Recurring Payments Merchant API (2.6.17)

Download OpenAPI specification:Download

Recurring payments is used for subscription payments, such as weekly dues for newspaper access, monthly dues for public transportation, etc. For details, see the Recurring API Guide.

Agreement v3 endpoints

List Agreements

The API endpoint allows merchant to fetch all agreements. If no query status is supplied it will default to only retrieving active agreements. There is no way to list all Agreements with all statuses, this is due to performance. Use the createdAfter query to paginate the response.

query Parameters
status
string (AgreementStatus)
Default: "ACTIVE"
Enum: "PENDING" "ACTIVE" "STOPPED" "EXPIRED"
Example: status=ACTIVE

Filter by the status of the agreement.

createdAfter
integer <int64>
Example: createdAfter=1644572442944

Filter by createdAfter timestamp (in milliseconds) for paginating.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Continuation-Token
string <uuid>

When returned from an endpoint, this indicates that there is more data than can be returned in one response. Repeating the request with the received token in the Continuation-Token header will return the next page of data. When not returned, the end of the data has been reached.

Continuation-Tokens are short-lived, so they cannot be used several minutes/hours after received.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
[]

Create a new Agreement, to be confirmed in the Vipps or MobilePay app

The API endpoint allows merchants to create agreements for a user to accept. Once the agreement is drafted, you will receive a vippsConfirmationUrl. This is used to redirect the user to the Vipps MobilePay landing page, or to the Vipps or MobilePay app when "isApp":true is used.

If the user accepts or rejects the agreement, the user will be redirected back to whichever URL has been passed in merchantRedirectUrl. You must implement polling on the agreement to check when the status changes to active, instead of relying on the redirect back to the merchantRedirectUrl. We have no control over if a user is actually redirected back or not, this depends on what browser the user came from.

Please note the different use cases for initialCharge and campaign. And when to use RESERVE_CAPTURE instead of DIRECT_CAPTURE as transactionType. More information about this can be found in the API documentation.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
any (campaignV3)
required
object (DraftAgreementPricingRequest)
phoneNumber
string <= 15 characters

Customers phone number (if available). Used to simplify the following interaction. MSISDN: https://en.wikipedia.org/wiki/MSISDN

object (InitialCharge)

An initial charge for a new agreement. The charge will be processed immediately when the user approves the agreement.

object (Time Period request)

A period of time, defined by a unit (DAY, WEEK, ...) and a count (number of said units)

isApp
boolean
Default: false

This optional parameter indicates whether payment request is triggered from Mobile App or Web browser. Based on this value, response will be redirect URL for Vipps MobilePay landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to us will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/knowledge-base/isApp

merchantAgreementUrl
required
string <= 1024 characters

URL where we can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in, not with username and password. We do not have any specific requirements for the security of the page other than requiring HTTPS. Only HTTPS scheme is allowed.

merchantRedirectUrl
required
string <= 1024 characters

URL where customer should be redirected after the agreement has been approved/rejected in the Vipps mobile application. HTTPS and deeplinks are allowed (example: myApp://home)

productName
required
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

scope
string

Space-separated list of the required user information (e.g., "name phoneNumber") for the agreement. See the Userinfo user guide for details. Possible values are:

  • name
  • address
  • email
  • phoneNumber
  • birthDate
  • nin
skipLandingPage
boolean
Default: false

If the property is set to true, it will cause a push notification to be sent to the given phone number immediately, without loading the landing page. This feature has to be specially enabled for eligible sales units: The sales units must be whitelisted by Vipps MobilePay. If the sales unit is not whitelisted, the request will fail and an error message will be returned (statusCode=403). See: https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page

externalId
string [ 1 .. 64 ] characters ^.{1,64}$

An optional external ID for the agreement. The externalId can be used by the merchant to map the agreementId to an ID in a subscription system or similar.

countryCode
string (CountryCode) ^[A-Z]{2}$
Enum: "NO" "DK" "FI"

Country code for the agreement according to ISO 3166-2 (two capital letters). Needs to be set based on the merchant's market/country. Cross border agreements are not supported, e.g., Norwegian merchants can only create agreements for Norwegian customers and countryCode should be NO.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{}

Fetch an Agreement

Fetch a single agreement for a user. Recommended to use when polling for status changes after sending an agreement to a user.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{}

Update an Agreement

Updates the agreement. Note that when updating the status to STOPPED, you can not re-activate it. If you want to pause an agreement, we suggest leaving the agreement active and skipping the creation of charges as long as the agreement is paused in your systems.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required

agreement

productName
string <= 45 characters

Name of the product being subscribed to.

productDescription
string <= 100 characters

Product description (longer)

merchantAgreementUrl
string <= 1024 characters

URL where we can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps MobilePay, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS.

externalId
string [ 1 .. 64 ] characters ^.{1,64}$

An optional external ID for the agreement. The externalId can be used by the merchant to map the agreementId to an ID in a subscription system or similar.

status
string
Value: "STOPPED"

Status of the agreement.

object (UpdateAgreementPricingRequest)
object

The interval of the agreement.

The interval is specified by the type and period properties. When the type is RECURRING, then the property period is required. When the type is FLEXIBLE, then the property period is not allowed.

Responses

Request samples

Content type
application/json
{
  • "productName": "Pluss-abonnement",
  • "productDescription": "string",
  • "merchantAgreementUrl": "https://example.com/vipps-subscriptions/1234/",
  • "externalId": "external-id-2468",
  • "status": "STOPPED",
  • "pricing": {
    },
  • "interval": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
Example
{}

Force accept an Agreement (Only available in test environment)

Forces an agreement to be accepted by the given customer phone number. This endpoint can only be used in the test environment.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
phoneNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "4712345678"
}

Response samples

Content type
application/json
{ }

Charge v3 endpoints

List Charges

Fetches all charges for a single agreement, including the optional initial charge. Supports filtering on status using query parameter.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

query Parameters
status
string (ChargeStatus)
Enum: "PENDING" "DUE" "RESERVED" "CHARGED" "PARTIALLY_CAPTURED" "FAILED" "CANCELLED" "PARTIALLY_REFUNDED" "REFUNDED" "PROCESSING"
Example: status=PENDING

Filter by status of the charge.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Continuation-Token
string <uuid>

When returned from an endpoint, this indicates that there is more data than can be returned in one response. Repeating the request with the received token in the Continuation-Token header will return the next page of data. When not returned, the end of the data has been reached.

Continuation-Tokens are short-lived, so they cannot be used several minutes/hours after received.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new charge

Creates a new recurring charge (payment) that will charge the user on the date specified. If the payment fails, the charge will be retried based on retryDays.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
amount
required
integer <int32> >= 100

Amount to be paid by the customer.

Amounts are specified in minor units. NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

transactionType
required
string (transactionType)
Enum: "DIRECT_CAPTURE" "RESERVE_CAPTURE"

Type of transaction, either direct capture or reserve capture

type
string (ChargeCreationTypeV3)
Default: "RECURRING"
Enum: "RECURRING" "UNSCHEDULED"
description
required
string [ 1 .. 60 ]

This field is visible to the end user in-app

due
string

The date when the charge is due to be processed.

Must be at least two days in advance in the production environment, and at least one day in the test environment.

If the charge is DIRECT_CAPTURE, the charge is processed and charged on the due date. If the charge is RESERVE_CAPTURE, the charge is RESERVED on due date.

Must be in the format YYYY-MM-DD and ISO 8601.

Required only for RECURRING charges

retryDays
integer <int32> [ 0 .. 14 ]

The service will attempt to charge the customer for the number of days specified in retryDays after the due date. We recommend at least two days retry.

Required only for RECURRING charges

orderId
string [ 1 .. 50 ] characters ^[a-zA-Z\d-]+

An optional, but recommended orderId for the charge. If provided, this will be the chargeId for this charge. This is the unique identifier of the payment, from the payment is initiated and all the way to the settlement data. See: https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/ If no orderId is specified, the chargeId will be automatically generated.

externalId
string [ 1 .. 64 ] characters ^.{1,64}$

An optional external ID for the charge, that takes the place of the orderId in settlement reports without overriding the default chargeId The externalId can be used by the merchant to map the chargeId to an ID in a subscription system or similar. Note that while orderId must be unique per merchant, externalId does not have this limitation, so you need to avoid assigning the same externalId to multiple charges if you want to keep them separate in settlement reports.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 49900,
  • "transactionType": "DIRECT_CAPTURE",
  • "description": "October",
  • "due": "2018-10-01",
  • "retryDays": 5,
  • "type": "RECURRING"
}

Response samples

Content type
application/json
{
  • "chargeId": "chg_WCVbcAbRCmu2zk"
}

Create multiple charges

Asynchronously creates multiple new recurring charges (payments) that will be automatically processed on the due date. If the payment fails, the charge will be retried based on retryDays.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
Array
agreementId
required
string

Id of a an agreement which user may agree to. Initially the agreement is in a pending state waiting for user approval. It enters active state once the user has approved it in the Vipps or MobilePay app

amount
required
integer <int32> >= 100

Amount to be paid by the customer.

Amounts are specified in minor units. NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

transactionType
required
string (transactionType)
Enum: "DIRECT_CAPTURE" "RESERVE_CAPTURE"

Type of transaction, either direct capture or reserve capture

description
required
string [ 1 .. 45 ]

This field is visible to the end user in-app

due
required
string

The date when the charge is due to be processed.

Must be at least two days in advance in the production environment, and at least one day in the test environment.

If the charge is DIRECT_CAPTURE, the charge is processed and charged on the due date. If the charge is RESERVE_CAPTURE, the charge is RESERVED on due date.

Must be in the format YYYY-MM-DD and ISO 8601.

retryDays
required
integer <int32> [ 0 .. 14 ]

The service will attempt to charge the customer for the number of days specified in retryDays after the due date. We recommend at least two days retry.

orderId
required
string [ 1 .. 50 ] characters ^[a-zA-Z\d-]+

This will be the chargeId for this charge. This is the unique identifier of the payment, from the payment is initiated and all the way to the settlement data. See: https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/

externalId
string [ 1 .. 64 ] characters ^.{1,64}$

An optional external ID for the charge, that takes the place of the orderId in settlement reports without overriding the default chargeId The externalId can be used by the merchant to map the chargeId to an ID in a subscription system or similar. Note that while orderId must be unique per merchant, externalId does not have this limitation, so you need to avoid assigning the same externalId to multiple charges if you want to keep them separate in settlement reports.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "invalidCharges": [
    ],
  • "validCharges": [
    ]
}

Fetch a charge

Fetch a single charge for a user.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{
  • "amount": 19900,
  • "currency": "NOK",
  • "description": "Premier League subscription: September",
  • "due": "2019-06-01T00:00:00Z",
  • "id": "chr_WCVbcA",
  • "agreementId": "agr_5kSeqz",
  • "externalId": "external-id-2468",
  • "externalAgreementId": "external-id-2468",
  • "retryDays": 5,
  • "status": "PENDING",
  • "transactionId": "5001419121",
  • "type": "RECURRING",
  • "transactionType": "DIRECT_CAPTURE",
  • "failureReason": "user_action_required",
  • "failureDescription": "User action required",
  • "summary": {
    },
  • "history": [
    ]
}

Cancel a charge

Cancels a pending, due or reserved charge. When cancelling a charge that is PARTIALLY_CAPTURED, the remaining funds on the charge will be released back to the customer.

Note if you cancel an agreement, there is no need to cancel the charges that belongs to the agreement. This will be done automatically.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json;charset=UTF-8
Example
{}

Fetch a charge by ID

A "special case" endpoint to fetch a single charge just by chargeId, when the agreementId is unknown. This is useful for investigating claims from customers, but not intended for automation.

Please note: This is not a replacement for the normal endpoint for fetching charges: GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}.

path Parameters
chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{
  • "amount": 19900,
  • "currency": "NOK",
  • "description": "Premier League subscription: September",
  • "due": "2019-06-01T00:00:00Z",
  • "id": "chr_WCVbcA",
  • "agreementId": "agr_5kSeqz",
  • "externalId": "external-id-2468",
  • "externalAgreementId": "external-id-2468",
  • "retryDays": 5,
  • "status": "PENDING",
  • "transactionId": "5001419121",
  • "type": "RECURRING",
  • "transactionType": "DIRECT_CAPTURE",
  • "failureReason": "user_action_required",
  • "failureDescription": "User action required",
  • "summary": {
    },
  • "history": [
    ]
}

Capture a reserved charge

Captures a reserved charge. Only charges with transactionType RESERVE_CAPTURE can be captured. Can also do partial captures (captures a smaller part of the payment).

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
amount
required
integer <int32> >= 100

The amount to capture on a reserved charge.

Amounts are specified in minor units. NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

description
required
string >= 1

A textual description of the operation, which will be displayed in the user's app.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "description": "Not all items were in stock. Partial capture."
}

Response samples

Content type
application/json;charset=UTF-8
Example
{}

Refund a charge

Refunds a charge, can also do a partial refund (refunding a smaller part of the payment).

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
amount
required
integer <int32> >= 100

The amount to refund on a captured/charged charge.

Amounts are specified in minor units. NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

description
required
string >= 1

A textual description of the operation, which will be displayed in the user's app.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "description": "Forgot to apply discount, refunding 50%"
}

Response samples

Content type
application/json;charset=UTF-8
Example
{}

Agreement v2 endpoints (deprecated)

Available until November 1, 2023

List Agreements Deprecated

The API endpoint allows merchant to fetch all agreements. If no query status is supplied, it will default to only retrieving active agreements. There is no way to list all agreements with all statuses; this is due to performance. Please note: Use the query parameters status and createdAfter specify the agreements you want to retrieve, in order to speed up the query. Try to avoid requests without query parameters. Set createdAfter to the most recent value as possible. For instance, if you fetch ACTIVE agreements every 24 hours, use createdAfter=now-25h or similar. Not that, in the future, it may be possible to encounter errors when the number of agreements in the response is too high (e.g., 413 Content Too Large or similar).

query Parameters
status
string (AgreementStatus)
Default: "ACTIVE"
Enum: "PENDING" "ACTIVE" "STOPPED" "EXPIRED"
Example: status=ACTIVE

Filter by the status of the agreement.

createdAfter
integer <int64>
Example: createdAfter=1644572442944

Filter by createdAfter timestamp (in milliseconds) for paginating.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
[]

Create a new Agreement, to be confirmed in the app Deprecated

The API endpoint allows merchants to create agreements for a user to accept. Once the agreement is drafted,you will receive a vippsConfirmationUrl. This is used to redirect the user to the landing page, or automatically app-switched to the app if "isApp":true is used.

If the user accepts or rejects the agreement, the user will be redirected back to the URL specified in merchantRedirectUrl. You have to implement polling on the agreement to check when the status changes to active instead of relying on the redirect back to the merchantRedirectUrl. We have no control over if a user is actually redirected back or not, this depends on what browser the user came from.

Please note the different use cases for initialCharge and campaign. And when to use RESERVE_CAPTURE instead of DIRECT_CAPTURE as transactionType. More information about this can be found in the API documentation.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
object (Variable Amount request)
object or null (Campaign request)
currency
required
string (Currency) = 3 characters ^[A-Z]{3}$
Default: "NOK"
Value: "NOK"
customerPhoneNumber
string [ 10 .. 15 ] characters ^\d{10,15}$

Customers phone number (if available). Used to simplify the following Vipps MobilePay interaction. The format is MSISDN: Digits only: Country code and subscriber number, but no prefix. If the phone number is a Norwegian phone number (+47) 91 23 45 67, the MSISDN representation is 4712345678. See: https://en.wikipedia.org/wiki/MSISDN

object (InitialCharge)

An initial charge for a new agreement. The charge will be processed immediately when the user approves the agreement.

interval
required
string (Interval) ^(YEAR|MONTH|WEEK|DAY)$
Default: "MONTH"
Enum: "YEAR" "MONTH" "WEEK" "DAY"

Interval for subscription

intervalCount
required
integer <int32> [ 1 .. 31 ]

Number of intervals between charges. Example: interval=week, intervalCount=2 to be able to charge every two weeks. Charges should occur at least once a year.

isApp
boolean
Default: false

This optional parameter indicates whether payment request is triggered from Mobile App or Web browser. Based on this value, response will be redirect URL for Vipps MobilePay landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to us will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/knowledge-base/isApp

merchantAgreementUrl
required
string <= 1024 characters

URL where you can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer management tools, not just information about how to contact customer service, etc. We recommend letting users log in, not with username and password. We do not have any specific requirements for the security of the page other than requiring HTTPS. Only HTTP or HTTPS scheme is allowed.

merchantRedirectUrl
required
string <= 1024 characters

URL where customer should be redirected after the agreement has been approved/rejected in the Vipps or MobilePay app. HTTPS and deeplinks are allowed (example: myApp://home)

price
required
integer <int32>

The price of the agreement.

Amounts are specified in minor units. NOK: 1 kr = 100 øre.

productName
required
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

scope
string

Space-separated list of the required user information (e.g., "name phoneNumber") for the agreement. See the Userinfo user guide for details. Possible values are:

  • name
  • address
  • email
  • phoneNumber
  • birthDate
  • nin
skipLandingPage
boolean
Default: false

If the property is set to true, it will cause a push notification to be sent to the given phone number immediately, without loading the landing page. This feature has to be specially enabled for eligible sales units: The sales units must be whitelisted by Vipps MobilePay. If the sales unit is not whitelisted, the request will fail and an error message will be returned (statusCode=403). See: https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page

Responses

Request samples

Content type
application/json
Example
{
  • "currency": "NOK",
  • "interval": "MONTH",
  • "intervalCount": 1,
  • "merchantRedirectUrl": "https://example.com/redirect",
  • "merchantAgreementUrl": "https://example.com/agreement",
  • "customerPhoneNumber": "12345678",
  • "price": 2500,
  • "productDescription": "MyNews on web",
  • "productName": "MyNews Digital",
  • "skipLandingPage": false
}

Response samples

Content type
application/json
{}

Fetch an Agreement Deprecated

Fetch a single agreement for a user. Recommended to use when polling for status changes after sending an agreement to a user.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{}

Update an Agreement Deprecated

Updates the agreement. Note that when updating the status to STOPPED, you can not re-activate it. If you want to pause an agreement, we suggest leaving the agreement active and skipping the creation of charges as long as the agreement is paused in your systems.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required

agreement

suggestedMaxAmount
integer <int32> [ 100 .. 2000000 ]

The suggested max amount that the customer should choose.

Amounts are specified in minor units. NOK: 1 kr = 100 øre.

object or null (Campaign request)
price
integer <int32> >= 0

The price of the agreement.

Price is specified in minor units. NOK: 1 kr = 100 øre.

productName
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

merchantAgreementUrl
string <= 1024 characters

URL where we can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps MobilePay, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS.

status
string
Value: "STOPPED"

Status of the agreement.

Responses

Request samples

Content type
application/json
{
  • "suggestedMaxAmount": 3000,
  • "campaign": {
    },
  • "price": 7900,
  • "productName": "Premier League subscription",
  • "productDescription": "Access to all games of English top football",
  • "merchantAgreementUrl": "https://example.com/vipps-subscriptions/1234/",
  • "status": "STOPPED"
}

Response samples

Content type
application/json
{
  • "agreementId": "agr_asdf123"
}

Update an Agreement Deprecated

Updates the agreement. Note that when updating the status to STOPPED, you can not re-activate it. If you want to pause an agreement, we suggest leaving the agreement active and skipping the creation of charges as long as the agreement is paused in your systems.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required

agreement

suggestedMaxAmount
integer <int32> [ 100 .. 2000000 ]

The suggested max amount that the customer should choose.

Amounts are specified in minor units. NOK: 1 kr = 100 øre.

object or null (Campaign request)
price
integer <int32> >= 0

The price of the agreement.

Price is specified in minor units. NOK: 1 kr = 100 øre.

productName
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

merchantAgreementUrl
string <= 1024 characters

URL where we can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps MobilePay, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS.

status
string
Value: "STOPPED"

Status of the agreement.

Responses

Request samples

Content type
application/json
{
  • "suggestedMaxAmount": 3000,
  • "campaign": {
    },
  • "price": 7900,
  • "productName": "Premier League subscription",
  • "productDescription": "Access to all games of English top football",
  • "merchantAgreementUrl": "https://example.com/vipps-subscriptions/1234/",
  • "status": "STOPPED"
}

Response samples

Content type
application/json
{
  • "agreementId": "agr_asdf123"
}

Force accept an Agreement (Only available in test environment) Deprecated

Forces an agreement to be accepted by the given customer phone number. This endpoint can only be used in the test environment.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
customerPhoneNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "customerPhoneNumber": "12345678"
}

Response samples

Content type
application/json
{ }

Charge v2 endpoints (deprecated)

Available until November 1, 2023

List Charges Deprecated

Fetches all charges for a single agreement, including the optional initial charge. Supports filtering on status using it as a query parameter.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

query Parameters
chargeStatus
string (ChargeStatus)
Enum: "PENDING" "DUE" "RESERVED" "CHARGED" "PARTIALLY_CAPTURED" "FAILED" "CANCELLED" "PARTIALLY_REFUNDED" "REFUNDED" "PROCESSING"
Example: chargeStatus=PENDING

Filter by status of the charge.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new charge Deprecated

Creates a new recurring charge (payment) that will charge the user on the date specified. If the payment fails, the charge will be retried based on retryDays. We recommend at least two days retry.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
amount
required
integer <int32> >= 100

Amount to be paid by the customer.

Amounts are specified in minor units. NOK: 1 kr = 100 øre.

currency
required
string (Currency) = 3 characters ^[A-Z]{3}$
Default: "NOK"
Value: "NOK"
description
required
string [ 1 .. 45 ]

This field is visible to the end user in-app

due
required
string

The date when the charge is due to be processed. Must be in the format YYYY-MM-DD and ISO 8601.

retryDays
required
integer <int32> [ 0 .. 14 ]

The service will attempt to charge the customer for the number of days specified in retryDays after the due date. We recommend at least two days retry.

orderId
string <= 50 ^[a-zA-Z\d-]+

An optional, but recommended orderId for the charge. If provided, this will be the chargeId for this charge. See: https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/ If no orderId is specified, the chargeId will be automatically generated.

Responses

Request samples

Content type
application/json
{
  • "amount": 19900,
  • "currency": "NOK",
  • "description": "Månedsabonnement",
  • "due": "2030-12-31",
  • "retryDays": 5,
  • "orderId": "acme-shop-123-order123abc"
}

Response samples

Content type
application/json
{
  • "chargeId": "chg_WCVbcAbRCmu2zk"
}

Fetch a Charge Deprecated

Fetch a single charge for a user.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{
  • "amount": 19900,
  • "amountRefunded": 0,
  • "description": "Premier League subscription: September",
  • "due": "2019-06-01T00:00:00Z",
  • "id": "chr_WCVbcA",
  • "status": "PENDING",
  • "transactionId": "5001419121",
  • "type": "RECURRING",
  • "failureReason": "user_action_required",
  • "failureDescription": "User action required"
}

Cancel a Charge Deprecated

Cancels a pending, due, or reserved charge. When cancelling a charge that is PARTIALLY_CAPTURED, the remaining funds on the charge will be released back to the customer.

Please note: If you cancel an agreement, all the charges for that agreement are automatically cancelled.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{
  • "amount": 19900,
  • "amountRefunded": 0,
  • "description": "Premier League subscription: September",
  • "due": "2019-06-01T00:00:00Z",
  • "id": "chr_WCVbcA",
  • "status": "PENDING",
  • "transactionId": "5001419121",
  • "type": "RECURRING",
  • "failureReason": "user_action_required",
  • "failureDescription": "User action required"
}

Capture a reserved charge Deprecated

Captures a reserved charge. Only charges with transactionType RESERVE_CAPTURE can be captured.

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Responses

Response samples

Content type
application/json
{ }

Refund a charge Deprecated

Refunds a charge, and can also do a partial refund (refunding a smaller part of the payment).

path Parameters
agreementId
required
string
Example: agr_5kSeqz

The agreement identifier (ID)

chargeId
required
string
Example: chr-123ab

The charge identifier (ID)

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API requests. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your sales unit. See API keys. Keep it secret.

Idempotency-Key
required
string

An Idempotency key must be provided to ensure idempotent requests. Key size can be between 1 to 40 characters. Key must not contain '#', '?', '/' or '\'

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps MobilePay merchants making payments for themselves.

Vipps-System-Name
string <= 30 characters
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good. See HTTP headers.

Vipps-System-Version
string <= 30 characters
Example: 5.4

The version number of the ecommerce solution. See HTTP headers.

Vipps-System-Plugin-Name
string <= 30 characters
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See HTTP headers.

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

The version number of the ecommerce plugin (if applicable). See HTTP headers.

Request Body schema: application/json
required
amount
required
integer <int32> >= 100

The amount to refund on a captured/charged charge.

Amounts are specified in minor units. NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

description
required
string >= 1

A textual description of the operation, which will be displayed in the user's app.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "description": "Forgot to apply discount, refunding 50%"
}

Response samples

Content type
application/json
{ }