Skip to main content
API docs by Redocly

Recurring Payments Merchant API (3.1.1)

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. It is recommended to use the pageNumber and pageSize 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.

pageNumber
integer <int32> >= 1
Example: pageNumber=1

Page number for paginating (should be used in combination with pageSize).

pageSize
integer <int32> [ 1 .. 2000 ]
Default: 500
Example: pageSize=500

Page size for paginating (must be used in combination with pageNumber).

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 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
(Price campaign (object or null)) or (Period campaign (object or null)) or (Event campaign (object or null)) (campaignV3)
required
any (PricingRequestV3)
phoneNumber
string or null <= 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: App flow

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, 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. This URL is required for Norwegian Merchants.

merchantRedirectUrl
required
string <= 2048 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: Landing page

externalId
string or null [ 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

Agreement with a set price and interval.

{}

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: 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/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "contextId": "string",
  • "extraDetails": [
    ]
}

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>

Amount to be paid by the customer, specified in minor units. See: Payment amounts.

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 .. 100 ] characters

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

processingMode
string (ProcessingMode)
Enum: "MULTIPLE_ATTEMPTS" "SINGLE_ATTEMPT"

Processing mode for the charge, either with or without retries. If set to SINGLE_ATTEMPT, the payment will not be retried if it fails. When using SINGLE_ATTEMPT, you must set retryDays to 0.

For RECURRING charges, the default is MULTIPLE_ATTEMPTS.

For UNSCHEDULED charges, the parameter cannot be set, as they by design are not retried.

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: orderid recommendations 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. Maximum 2000 charges per request.

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>

Amount to be paid by the customer, specified in minor units See: Payment amounts.

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

Type of transaction, either direct capture or reserve capture

description
required
string [ 1 .. 100 ] characters

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.

processingMode
string (ProcessingMode)
Enum: "MULTIPLE_ATTEMPTS" "SINGLE_ATTEMPT"

Processing mode for the charge, either with or without retries. If set to SINGLE_ATTEMPT, the payment will not be retried if it fails. When using SINGLE_ATTEMPT, you must set retryDays to 0.

For RECURRING charges, the default is MULTIPLE_ATTEMPTS.

For UNSCHEDULED charges, the parameter cannot be set, as they by design are not retried.

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: orderid recommendations

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,
  • "processingMode": "MULTIPLE_ATTEMPTS",
  • "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/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "contextId": "string",
  • "extraDetails": [
    ]
}

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,
  • "processingMode": "MULTIPLE_ATTEMPTS",
  • "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>

The amount to capture on a reserved charge, specified in minor units. See: Payment amounts.

description
string [ 1 .. 100 ] characters
Deprecated

Deprecated. Description in CreateChargeV3 is used instead.

Responses

Request samples

Content type
application/json
{
  • "amount": 5000,
  • "description": "TV subscription for May"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "contextId": "string",
  • "extraDetails": [
    ]
}

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>

The amount to refund on a captured/charged charge, specified in minor units. See: Payment amounts.

description
required
string non-empty

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/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "contextId": "string",
  • "extraDetails": [
    ]
}