Skip to main content
API docs by Redocly

Recurring Payments Merchant API (2.6.16)

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 v2 endpoints (deprecated)

Will not be available from November 1, 2023

List Agreements Deprecated

The API call 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 status of the agreement.

createdAfter
integer <int32>
Example: createdAfter=1644572442944

Filter by createdAfter timestamp for paginating.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 Vipps Deprecated

The API call 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 landing page, or to the Vipps app if "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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
object (Variable Amount request)
object or null (Campaign request)
currency
required
string (Currency) = 3 characters ^[A-Z]{3}$
Default: "NOK"
Value: "NOK"
customerPhoneNumber
string <= 15 characters

Customers phone number (if available). Used to simplify the following Vipps 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.

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 landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to Vipps will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/common-topics/isApp

merchantAgreementUrl
required
string <= 1024 characters

URL where Vipps 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 with Vipps, 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 mobile application. HTTPS and deeplinks are allowed (example: myApp://home)

price
required
integer <int32>

The price of the agreement.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

productName
required
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

scope
string

Space separated list of the user profile-data scope to require for the agreement.

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 by Vipps for eligible sales units: The sales units must be whitelisted by Vipps. 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/common-topics/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": "45678272",
  • "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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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

agreement

suggestedMaxAmount
integer <int32> [ 100 .. 2000000 ]

The suggested max amount that the customer should choose.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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

The price of the agreement.

Price is specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

productName
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

merchantAgreementUrl
string <= 1024 characters

URL where Vipps 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, 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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

agreement

suggestedMaxAmount
integer <int32> [ 100 .. 2000000 ]

The suggested max amount that the customer should choose.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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

The price of the agreement.

Price is specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

productName
string <= 45 characters

Product name (short)

productDescription
string <= 100 characters

Product description (longer)

merchantAgreementUrl
string <= 1024 characters

URL where Vipps 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, 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
customerPhoneNumber
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Agreement v3 endpoints

List Agreements

The API call 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 status of the agreement.

createdAfter
integer <int32>
Example: createdAfter=1644572442944

Filter by createdAfter timestamp for paginating.

header Parameters
Authorization
required
string

The access token is a base64-encoded string that is required for all API calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 Vipps

The API call 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 landing page, or to the Vipps app if "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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
any (campaignV3)
required
object (DraftAgreementPricingRequest)
phoneNumber
string <= 15 characters

Customers phone number (if available). Used to simplify the following Vipps 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.

required
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 landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to Vipps will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/common-topics/isApp

merchantAgreementUrl
required
string <= 1024 characters

URL where Vipps 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, 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 user profile-data scope to require for the agreement.

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 by Vipps for eligible sales units: The sales units must be whitelisted by Vipps. 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/common-topics/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^[A-Z]{2}$
Value: "NO"

An optional country code for the agreement according to ISO 3166-2 (two capital letters)

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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

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 Vipps 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, 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)

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": {
    }
}

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
phoneNumber
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Charge v2 endpoints (deprecated)

Will not be available from November 1, 2023

List Charges Deprecated

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
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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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.

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
amount
required
integer <int32> >= 100

Amount to be paid by the customer.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 ø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.

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

An optional orderId for the payment, auto generated otherwise.

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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.

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

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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, 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
amount
required
integer <int32> >= 100

The amount to refund on a captured/charged charge.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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
{ }

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
amount
required
integer <int32> >= 100

Amount to be paid by the customer.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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.

If the charge is DIRECT_CAPTURE, the charge is processed and charged on 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.

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

An optional orderId for the payment, auto generated otherwise

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

An optional external id for the charge The externalId can be used by the merchant to map the chargeId to an id in a subscription system or similar.

Responses

Request samples

Content type
application/json
{
  • "amount": 19900,
  • "transactionType": "DIRECT_CAPTURE",
  • "description": "Månedsabonnement",
  • "due": "2030-12-31",
  • "retryDays": 5,
  • "orderId": "acme-shop-123-order123abc",
  • "externalId": "external-id-2468"
}

Response samples

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

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 by Vipps.

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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

Fetch a single charge just by chargeId, when the agreementId is unknown. Useful for investigating claims from customers, but not intended for automation. This is not a replacement for the normal endpoint for fetching charges: GET:/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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
amount
required
integer <int32> >= 100

The amount to capture on a reserved charge.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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 calls. 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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 that this payment is made for. This is a required parameter if you are a Vipps 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 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
amount
required
integer <int32> >= 100

The amount to refund on a captured/charged charge.

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

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
{}