Recurring Payments Merchant API (2.6.15)
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.
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
[- {
- "campaign": {
- "campaignPrice": 1500,
- "end": "2022-12-31T00:00:00Z"
}, - "currency": "NOK",
- "id": "agr_DdLnJAF",
- "interval": "MONTH",
- "intervalCount": 2,
- "price": 49900,
- "productName": "Premier League subscription",
- "productDescription": "Access to all games of English top football",
- "start": "2019-01-01T00:00:00Z",
- "stop": null,
- "status": "ACTIVE",
- "sub": "8d7de74e-0243-11eb-adc1-0242ac120002",
- "variableAmount": {
- "suggestedMaxAmount": 3000,
- "maxAmount": 3000
}
}
]
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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 This 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. |
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. 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. |
merchantRedirectUrl required | string <= 1024 characters URL where customer should be redirected after the agreement has been approved/rejected in the Vipps mobile application. |
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 If the property is set to |
Responses
Request samples
- Payload
{- "currency": "NOK",
- "interval": "MONTH",
- "intervalCount": 1,
- "customerPhoneNumber": "45678272",
- "price": 2500,
- "productDescription": "MyNews on web",
- "productName": "MyNews Digital",
- "skipLandingPage": false
}
Response samples
- 201
- default
{- "agreementId": "agr_5kSeqz",
- "chargeId": "chr_5kSeqz"
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "campaign": {
- "campaignPrice": 1500,
- "end": "2022-12-31T00:00:00Z"
}, - "currency": "NOK",
- "id": "agr_DdLnJAF",
- "interval": "MONTH",
- "intervalCount": 2,
- "price": 49900,
- "productName": "Premier League subscription",
- "productDescription": "Access to all games of English top football",
- "start": "2019-01-01T00:00:00Z",
- "stop": null,
- "status": "ACTIVE",
- "sub": "8d7de74e-0243-11eb-adc1-0242ac120002",
- "variableAmount": {
- "suggestedMaxAmount": 3000,
- "maxAmount": 3000
}
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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: 15 kr = 1500 ø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: 15 kr = 1500 ø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. 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. |
status | string Value: "STOPPED" Status of the agreement. |
Responses
Request samples
- Payload
{- "suggestedMaxAmount": 3000,
- "campaign": {
- "campaignPrice": 1500,
- "end": "2022-12-31T00:00:00Z"
}, - "price": 7900,
- "productName": "Premier League subscription",
- "productDescription": "Access to all games of English top football",
- "status": "STOPPED"
}
Response samples
- 200
- default
{- "agreementId": "agr_asdf123"
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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: 15 kr = 1500 ø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: 15 kr = 1500 ø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. 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. |
status | string Value: "STOPPED" Status of the agreement. |
Responses
Request samples
- Payload
{- "suggestedMaxAmount": 3000,
- "campaign": {
- "campaignPrice": 1500,
- "end": "2022-12-31T00:00:00Z"
}, - "price": 7900,
- "productName": "Premier League subscription",
- "productDescription": "Access to all games of English top football",
- "status": "STOPPED"
}
Response samples
- 200
- default
{- "agreementId": "agr_asdf123"
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Request Body schema: application/json
customerPhoneNumber required | string |
Responses
Request samples
- Payload
{- "customerPhoneNumber": "91234567"
}
Response samples
- 200
- default
{ }
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
[- {
- "campaign": {
- "type": "PRICE_CAMPAIGN",
- "price": 1500,
- "end": "2022-12-31T00:00:00Z",
- "explanation": "Ordinary price 399 kr starts 6/12/2022"
}, - "pricing": {
- "type": "LEGACY",
- "currency": "NOK",
- "amount": 1500,
- "suggestedMaxAmount": 30000,
- "maxAmount": 30000
}, - "id": "agr_DdLnJAF",
- "interval": {
- "unit": "WEEK",
- "count": 2,
- "text": "every 2 weeks"
}, - "productName": "Premier League subscription",
- "productDescription": "string",
- "start": "2019-01-01T00:00:00Z",
- "stop": null,
- "status": "ACTIVE",
- "sub": "8d7de74e-0243-11eb-adc1-0242ac120002",
}
]
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Request Body schema: application/json
any (campaignV3) | |
required | object (pricing) |
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 If merchant is redirecting user from an app or a mobile device. |
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. 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. |
merchantRedirectUrl required | string <= 1024 characters URL where customer should be redirected after the agreement has been approved/rejected in the Vipps mobile application. |
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 If the property is set to |
externalId | string <= 64 characters An optional external id for the agreement |
Responses
Request samples
- Payload
{- "pricing": {
- "type": "LEGACY",
- "amount": 2500,
- "currency": "NOK"
}, - "interval": {
- "unit": "MONTH",
- "count": 1
}, - "customerPhoneNumber": "45678272",
- "productName": "MyNews Digital"
}
Response samples
- 201
- default
{- "agreementId": "agr_5kSeqz",
- "chargeId": "chr_5kSeqz"
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "campaign": {
- "type": "PRICE_CAMPAIGN",
- "price": 1500,
- "end": "2022-12-31T00:00:00Z",
- "explanation": "Ordinary price 399 kr starts 6/12/2022"
}, - "pricing": {
- "type": "LEGACY",
- "currency": "NOK",
- "amount": 1500,
- "suggestedMaxAmount": 30000,
- "maxAmount": 30000
}, - "id": "agr_DdLnJAF",
- "interval": {
- "unit": "WEEK",
- "count": 2,
- "text": "every 2 weeks"
}, - "productName": "Premier League subscription",
- "productDescription": "string",
- "start": "2019-01-01T00:00:00Z",
- "stop": null,
- "status": "ACTIVE",
- "sub": "8d7de74e-0243-11eb-adc1-0242ac120002",
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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. 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. |
status | string Value: "STOPPED" Status of the agreement. |
object (pricing) |
Responses
Request samples
- Payload
{- "productName": "Pluss-abonnement",
- "productDescription": "string",
- "status": "STOPPED",
- "pricing": {
- "amount": 1500,
- "suggestedMaxAmount": 3000
}
}
Response samples
- default
{- "title": "Bad Request",
- "status": 400,
- "detail": "Input validation failed",
- "instance": "/v3/agreements",
- "contextId": "f70b8bf7-c843-4bea-95d9-94725b19895f",
- "extraDetails": [
- {
- "field": "productName",
- "text": "must not be empty"
}
]
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Request Body schema: application/json
phoneNumber required | string |
Responses
Request samples
- Payload
{- "phoneNumber": "91234567"
}
Response samples
- 204
- default
{ }
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
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
[- {
- "amount": 234,
- "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"
}
]
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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 |
retryDays required | integer <int32> [ 0 .. 14 ] The service will attempt to charge the customer for N days |
orderId | string <= 50 ^[a-zA-Z\d-]+ An optional orderId for the payment, auto generated otherwise |
Responses
Request samples
- Payload
{- "amount": 234,
- "currency": "NOK",
- "description": "Månedsabonnement",
- "due": "2030-12-31",
- "retryDays": 5,
- "orderId": "acme-shop-123-order123abc"
}
Response samples
- 201
- default
{- "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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "amount": 234,
- "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
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "amount": 234,
- "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
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{ }
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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: 15 kr = 1500 øre. |
description required | string >= 1 A textual description of the operation, which will be displayed in the user's app. |
Responses
Request samples
- Payload
{- "amount": 5000,
- "description": "Forgot to apply discount, refunding 50%"
}
Response samples
- 200
- default
{ }
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
[- {
- "amount": 234,
- "currency": "NOK",
- "description": "Premier League subscription: September",
- "due": "2019-06-01T00:00:00Z",
- "id": "chr_WCVbcA",
- "agreementId": "agr_5kSeqz",
- "status": "PENDING",
- "transactionId": "5001419121",
- "type": "RECURRING",
- "transactionType": "DIRECT_CAPTURE",
- "failureReason": "user_action_required",
- "failureDescription": "User action required",
- "summary": {
- "captured": 234,
- "refunded": 0,
- "cancelled": 234
}, - "history": [
- {
- "occurred": "2022-09-05T14:25:55Z",
- "event": "RESERVE",
- "amount": 234,
- "idempotencyKey": "string",
- "success": true
}
]
}
]
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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 | 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 Must be in the format |
retryDays required | integer <int32> [ 0 .. 14 ] The service will attempt to charge the customer for N days |
orderId | string <= 50 ^[a-zA-Z\d-]+ An optional orderId for the payment, auto generated otherwise |
Responses
Request samples
- Payload
{- "amount": 234,
- "transactionType": "DIRECT_CAPTURE",
- "description": "Månedsabonnement",
- "due": "2030-12-31",
- "retryDays": 5,
- "orderId": "acme-shop-123-order123abc"
}
Response samples
- 201
- default
{- "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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "amount": 234,
- "currency": "NOK",
- "description": "Premier League subscription: September",
- "due": "2019-06-01T00:00:00Z",
- "id": "chr_WCVbcA",
- "agreementId": "agr_5kSeqz",
- "status": "PENDING",
- "transactionId": "5001419121",
- "type": "RECURRING",
- "transactionType": "DIRECT_CAPTURE",
- "failureReason": "user_action_required",
- "failureDescription": "User action required",
- "summary": {
- "captured": 234,
- "refunded": 0,
- "cancelled": 234
}, - "history": [
- {
- "occurred": "2022-09-05T14:25:55Z",
- "event": "RESERVE",
- "amount": 234,
- "idempotencyKey": "string",
- "success": true
}
]
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- default
{- "title": "Bad Request",
- "status": 400,
- "detail": "Input validation failed",
- "instance": "/v3/agreements",
- "contextId": "f70b8bf7-c843-4bea-95d9-94725b19895f",
- "extraDetails": [
- {
- "field": "productName",
- "text": "must not be empty"
}
]
}
Fetch a charge by id
Fetch a single charge just by chargeId. Useful for investigating claims from customers, but not intended for automation.
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
Responses
Response samples
- 200
- default
{- "amount": 234,
- "currency": "NOK",
- "description": "Premier League subscription: September",
- "due": "2019-06-01T00:00:00Z",
- "id": "chr_WCVbcA",
- "agreementId": "agr_5kSeqz",
- "status": "PENDING",
- "transactionId": "5001419121",
- "type": "RECURRING",
- "transactionType": "DIRECT_CAPTURE",
- "failureReason": "user_action_required",
- "failureDescription": "User action required",
- "summary": {
- "captured": 234,
- "refunded": 0,
- "cancelled": 234
}, - "history": [
- {
- "occurred": "2022-09-05T14:25:55Z",
- "event": "RESERVE",
- "amount": 234,
- "idempotencyKey": "string",
- "success": true
}
]
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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: 15 kr = 1500 øre. |
description required | string >= 1 A textual description of the operation, which will be displayed in the user's app. |
Responses
Request samples
- Payload
{- "amount": 5000,
- "description": "Not all items were in stock. Partial capture."
}
Response samples
- default
{- "title": "Bad Request",
- "status": 400,
- "detail": "Input validation failed",
- "instance": "/v3/agreements",
- "contextId": "f70b8bf7-c843-4bea-95d9-94725b19895f",
- "extraDetails": [
- {
- "field": "productName",
- "text": "must not be empty"
}
]
}
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
|
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 |
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 Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. |
Vipps-System-Version | string Example: 5.4 The version number of the ecommerce solution. |
Vipps-System-Plugin-Name | string Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. |
Vipps-System-Plugin-Version | string Example: 1.2.1 The version number of the ecommerce plugin (if applicable). |
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: 15 kr = 1500 øre. |
description required | string >= 1 A textual description of the operation, which will be displayed in the user's app. |
Responses
Request samples
- Payload
{- "amount": 5000,
- "description": "Forgot to apply discount, refunding 50%"
}
Response samples
- default
{- "title": "Bad Request",
- "status": 400,
- "detail": "Input validation failed",
- "instance": "/v3/agreements",
- "contextId": "f70b8bf7-c843-4bea-95d9-94725b19895f",
- "extraDetails": [
- {
- "field": "productName",
- "text": "must not be empty"
}
]
}