Skip to content

Instantly share code, notes, and snippets.

@ianmurrays

ianmurrays/epayment-swagger-id.yaml

Created April 4, 2025 08:08
Show Gist options
  • Save ianmurrays/7492d62bf3de0bda84d74df970eab971 to your computer and use it in GitHub Desktop.
Save ianmurrays/7492d62bf3de0bda84d74df970eab971 to your computer and use it in GitHub Desktop.
Download ZIP
Vipps MobilePay Recurring & ePayment OpenAPI Spec
Raw
epayment-swagger-id.yaml
openapi: 3.0.0
servers:
- url: https://api.vipps.no/epayment
description: >-
Production environment (uses the production API keys, the official app and
live data)
- url: https://apitest.vipps.no/epayment
description: Test environment (uses the test API keys, the test app and test data)
info:
description: >-
The ePayment API enables you to create Vipps MobilePay payments for online
and in-person payments.
See the [ePayment API
Guide](https://developer.vippsmobilepay.com/docs/APIs/epayment-api)
for more details.
version: 1.7.0
title: ePayment API
contact:
name: Vipps MobilePay AS
url: https://developer.vippsmobilepay.com/
license:
name: MIT
url: https://choosealicense.com/licenses/mit/
termsOfService: https://vippsmobilepay.com/legal/terms-and-conditions/
x-logo:
url: >-
https://vipps.no/static/vipps_frontend/311340/media/extra-images/vipps-logo.svg
backgroundColor: '#FFFFFF'
altText: Logo
tags:
- description: Create payment endpoints
name: CreatePayments
- description: Query payments endpoints
name: QueryPayments
- description: Adjust payments endpoints
name: AdjustPayments
- description: Force approve payments endpoints
name: ForceApprove
paths:
/v1/payments:
parameters:
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/APIM-Subscription-Key'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
post:
operationId: createPayment
summary: Create a payment
tags:
- CreatePayments
description: Create a new payment
requestBody:
description: New `CreatePaymentRequest` body.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
responses:
'201':
$ref: '#/components/responses/CreatePaymentResponse'
'400':
$ref: '#/components/responses/ProblemResponse'
'403':
$ref: '#/components/responses/ProblemResponse'
'409':
$ref: '#/components/responses/ProblemResponse'
/v1/payments/{Reference}:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
get:
summary: Get a payment
tags:
- QueryPayments
responses:
'200':
$ref: '#/components/responses/GetPaymentResponse'
operationId: getPayment
description: Get a payment object by its `reference` id.
/v1/payments/{Reference}/events:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
get:
summary: Get a payment's event log
tags:
- QueryPayments
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PaymentEvent'
operationId: getPaymentEventLog
security:
- Bearer-Authorization: []
description: Get event log for the specified payment's `reference` id.
/v1/payments/{Reference}/cancel:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
post:
summary: Cancel a payment
operationId: cancelPayment
requestBody:
description: New `CancelModificationRequest` body.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CancelModificationRequest'
responses:
'200':
$ref: '#/components/responses/AdjustResponse'
'400':
$ref: '#/components/responses/ProblemResponse'
'404':
$ref: '#/components/responses/ProblemResponse'
'409':
$ref: '#/components/responses/ProblemResponse'
description: Cancel the payment with the specified `reference` id.
security:
- Bearer-Authorization: []
tags:
- AdjustPayments
/v1/payments/{Reference}/capture:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
post:
summary: Capture a payment
operationId: capturePayment
responses:
'200':
$ref: '#/components/responses/AdjustResponse'
'400':
$ref: '#/components/responses/ProblemResponse'
'404':
$ref: '#/components/responses/ProblemResponse'
'409':
$ref: '#/components/responses/ProblemResponse'
description: Capture the given payment
security:
- Bearer-Authorization: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CaptureModificationRequest'
description: Requested capture modification
tags:
- AdjustPayments
/v1/payments/{Reference}/refund:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
post:
summary: Refund a payment
operationId: refundPayment
responses:
'200':
$ref: '#/components/responses/AdjustResponse'
'400':
$ref: '#/components/responses/ProblemResponse'
'404':
$ref: '#/components/responses/ProblemResponse'
'409':
$ref: '#/components/responses/ProblemResponse'
description: Refund the given payment
security:
- Bearer-Authorization: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefundModificationRequest'
description: Requested refund modification
tags:
- AdjustPayments
/v1/test/payments/{Reference}/approve:
parameters:
- $ref: '#/components/parameters/Payment-Reference-ID'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/APIM-Subscription-Key'
post:
summary: Force approve a payment
tags:
- ForceApprove
responses:
'200':
description: OK
operationId: forceApprove
description: >-
This endpoint is only available in the test environment.
It allows developers to approve a payment through the ePayment API
without the use of the Vipps or MobilePay app. This is useful for
automated testing.
Express checkout is not supported for this endpoint.
Attempted use in production is not allowed, and will fail.
Important: All test users must manually approve at least one payment
in the Vipps or MobilePay app before this endpoint can be used for that
user.
security:
- Bearer-Authorization: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ForceApprove'
description: Force approve request body
components:
schemas:
Customer:
title: Customer
type: object
description: >-
The target customer if the identity is known.
The customer can be specified either with phone number, the customer
token
or with the user's personal QR code
Specifying more than one of these will result in an error.
oneOf:
- $ref: '#/components/schemas/CustomerPhoneNumber'
- $ref: '#/components/schemas/PersonalQrCode'
- $ref: '#/components/schemas/CustomerToken'
x-examples:
example phonenumber:
phoneNumber: '4712345678'
example personal Qr:
personalQr: https://qr.vipps.no/p/{{internationalMobileNumber}}
CustomerPhoneNumber:
title: Customer phone number
type: object
description: >-
The customer's phone number, if available.
**Please note:** The phone number (and QR code) is optional and should
only be sent if it is
already known. Users should never be asked for the phone number, as they
will
either be automatically app-switched to the Vipps or MobilePay app, or
they will be presented
with the landing page. The exception for this is "manual POS"
integration,
where the cashier asks the customer for the number, and then enters it
manually on the POS.
If the customer's phone number is needed by the merchant,
use `scope` and the [Userinfo
API](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/).
See also [Landing
page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/).
properties:
phoneNumber:
type: string
description: >-
The phone number of the user paying the transaction with Vipps
MobilePay.
The format is MSISDN: Digits only: Country code and subscriber
number, but no prefix.
If the phone number is a Norwegian phone number `(+47) 91 23 45 67`,
the MSISDN representation is `4712345678`.
See: https://en.wikipedia.org/wiki/MSISDN
minLength: 10
maxLength: 15
example: '4712345678'
pattern: ^\d{10,15}$
PersonalQrCode:
title: Personal QR code
type: object
description: >-
The full content of the user's personal QR code in the app, used in
'merchant scan' scenarios.
After the personal QR code has been scanned in a physical context, send
the complete QR
code content in this field to initiate a payment from the user (and do
not send `phoneNumber`).
**Important:** The content of the QR code can change at any time,
without warning.
It is very important to send the _complete content of the QR code_, like
the complete URL in the example below.
While the personal QR code does reveal the user's phone number in this
example, that may change.
The [Userinfo
API](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/)
should be used if you need the user to share personal information,
such as phone number, email address, etc.
properties:
personalQr:
type: string
description: The full content of the user's personal QR code in the app.
minLength: 5
maxLength: 255
example: https://qr.vipps.no/28/2/01/031/4712345678?v=1
CustomerToken:
title: Customer token
type: object
description: >-
The customer's token, if it is available. This token will be sent as
part of the user.checked-in.v1 webhook event when a user scans a
merchant callback QR
properties:
customerToken:
type: string
description: A distinct token per customer.
example: ey%382jf8+qk3nnfdsao0i5jlalidugujnakgo9t8ghn
Amount:
description: Amount object, containing a `value` and a `currency`.
type: object
properties:
currency:
$ref: '#/components/schemas/Currency'
value:
type: integer
minimum: 0
maximum: 65000000
example: 49900
format: int64
description: >-
Amounts are specified in minor units (i.e., integers with two
trailing zeros).
For example: 10.00 NOK should be written as 1000.
The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.
required:
- value
- currency
Currency:
type: string
example: NOK
enum:
- NOK
- DKK
- EUR
description: Available types of currency are NOK, DKK, and EUR.
Metadata:
type: object
description: >-
Metadata is a key-value map that can be used to store additional
information about the payment. The metadata is not used by Vipps
MobilePay, but is passed through in the `GetPaymentResponse` object.
Key length is limited to 100 characters, and value length is limited to
500 characters.
Max capacity is 5 key-value pairs.
additionalProperties:
type: string
maxProperties: 5
example:
key1: value1
key2: value2
key3: value3
nullable: true
CreatePaymentRequest:
title: Create payment request
description: The `CreatePaymentRequest` object.
type: object
x-examples:
example with order lines:
amount:
value: 1234
currency: NOK
paymentMethod:
type: WALLET
customer:
phoneNumber: '4796844569'
reference: acme-shop-123-order123abc
userFlow: PUSH_MESSAGE
returnUrl: https://example.com/redirect?reference=577531713174689605
expiresAt: '2024-05-01T13:03:56+02:00'
paymentDescription: Purchase of socks
receipt:
orderLines:
- name: Vipps socks
id: '1234567890'
totalAmount: 1000
totalAmountExcludingTax: 800
totalTaxAmount: 200
taxPercentage: 25
unitInfo:
unitPrice: 500
quantity: '2'
quantityUnit: PCS
discount: 2000
productUrl: https://example.com/store/socks
isReturn: false
isShipping: false
- name: Vipps Hoodie
id: '1234567890'
totalAmount: 11000
totalAmountExcludingTax: 10000
totalTaxAmount: 1000
taxPercentage: 10
unitInfo:
unitPrice: 11000
quantity: '1'
quantityUnit: PCS
discount: 0
productUrl: https://example.com/store/socks
isReturn: false
isShipping: false
bottomLine:
currency: NOK
tipAmount: 2000
giftCardAmount: 20000
posId: I will put posId in here
totalAmount: 0
totalTax: 0
totalDiscount: 0
shippingAmount: 0
shippingInfo:
amount: 1000
amountExcludingTax: 1000
taxAmount: 250
taxPercentage: 25
paymentSources:
giftCard: 0
card: 0
voucher: 0
cash: 0
barcode:
format: EAN-13
data: string
receiptNumber: receiptnumberyolo
example with personal Qr:
amount:
value: 1234
currency: NOK
paymentMethod:
type: WALLET
customer:
personalQr: https://qr.vipps.no/p/4796844569
reference: acme-shop-123-order123abc
userFlow: PUSH_MESSAGE
returnUrl: https://example.com/redirect?reference=577531713174932058
paymentDescription: Purchase of socks
example with user info:
amount:
value: 1234
currency: NOK
paymentMethod:
type: WALLET
customer:
phoneNumber: 4796844569
reference: acme-shop-123-order123abc
userFlow: PUSH_MESSAGE
returnUrl: https://example.com/redirect?reference=577531713175705837
paymentDescription: Purchase of socks
profile:
scope: name phoneNumber address birthDate
properties:
amount:
$ref: '#/components/schemas/Amount'
customer:
$ref: '#/components/schemas/Customer'
minimumUserAge:
type: integer
nullable: true
minimum: 0
maximum: 100
example: 16
description: Minimum age in years required for the customer to make the purchase.
customerInteraction:
type: string
description: >-
The type of customer interaction that triggers the purchase.
`CUSTOMER_PRESENT` means that the customer is physically present at
the
point of sale when the payment is made, typically in a store.
enum:
- CUSTOMER_PRESENT
- CUSTOMER_NOT_PRESENT
x-enum-varnames:
- CUSTOMER_PRESENT
- CUSTOMER_NOT_PRESENT
example: CUSTOMER_NOT_PRESENT
default: CUSTOMER_NOT_PRESENT
industryData:
$ref: '#/components/schemas/IndustryData'
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
profile:
$ref: '#/components/schemas/ProfileRequest'
reference:
$ref: '#/components/schemas/Reference'
returnUrl:
type: string
example: https://example.com/redirect?orderId=acme-shop-123-order123abc
description: |-
The URL the user is returned to after the payment session.
The URL must use the `https://` scheme or a custom URL scheme.
userFlow:
type: string
enum:
- PUSH_MESSAGE
- NATIVE_REDIRECT
- WEB_REDIRECT
- QR
x-enum-varnames:
- PUSH_MESSAGE
- NATIVE_REDIRECT
- WEB_REDIRECT
- QR
example: WEB_REDIRECT
description: >-
The flow for bringing the user to the Vipps or MobilePay app's
payment confirmation screen.
If `userFlow` is `PUSH_MESSAGE`, a valid value for `customer` is
required.
If `userFlow` is `WEB_REDIRECT`, a valid value for `returnUrl` is
required.
`WEB_REDIRECT` is the normal flow for browser-based payment flows.
If on a mobile device, the Vipps or MobilePay app will open. A valid
value for `returnUrl` is required.
Otherwise, the [landing
page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/)
will open.
`PUSH_MESSAGE` is to skip the landing page for payments initiated on
a device other than the user's phone.
The user gets a push message that opens the payment in the app. This
requires a valid `customer` field.
`QR` returns a QR code that can be scanned to complete the payment.
`NATIVE_REDIRECT` is not recommended, except in some cases where
merchant doesn’t have web presence.
It provides automatic app-switch between the merchant's native app
and the Vipps or MobilePay app.
We recommend using `WEB_REDIRECT` instead.
expiresAt:
type: string
example: '2023-02-26T17:32:28Z'
pattern: >-
^((?:(\d{4}-\d{2}-\d{2})(T|t)(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|z|([+-](?:2[0-3]|[01][0-9]):[0-5][0-9])))$
nullable: true
description: >-
Only relevant for Long-living payment requests, which require
special approval. See:
https://developer.vippsmobilepay.com/docs/APIs/epayment-api/features/long-living-payments/
The payment will expire at the given date and time.
The format must adhere to RFC 3339.
The value must be more than 10 minutes and less than 60 days in the
future.
Can only be combined with `userFlow: PUSH_MESSAGE` or `userFlow:
QR`.
If `ExpiresAt` is set, `receipt` also must be set.
qrFormat:
nullable: true
type: object
description: >-
Optional setting that is only applicable when `userFlow` is set to
`QR`.
This is used to set the format for the QR code.
properties:
format:
type: string
enum:
- TEXT/TARGETURL
- IMAGE/SVG+XML
- IMAGE/PNG
example: IMAGE/SVG+XML
description: >-
If `userFlow` is `QR` and `qrFormat` is not set, the QR code
image will be returned as `SVG+XML`, by default.
default: IMAGE/SVG+XML
size:
type: integer
example: 1024
description: >-
For example, if the value is 200, then 200x200 px is set as the
dimension for the QR code.
This is only applicable when the format is set to `PNG`. If not
set, the default is 1024.
minimum: 100
maximum: 2000
nullable: true
required:
- format
paymentDescription:
type: string
minLength: 3
maxLength: 100
description: |-
The payment description summary that will be provided to the user
through the app, the merchant portal, and the settlement files.
See the [recommendations](/docs/knowledge-base/transactiontext/).
example: >-
Temporary reservation of maximum amount. You will only be charged
for the actual use.
receipt:
$ref: '#/components/schemas/Receipt'
metadata:
$ref: '#/components/schemas/Metadata'
receiptUrl:
type: string
description: |-
The URL where a receipt can be viewed or downloaded.
The URL must use the `https://` scheme or a custom URL scheme.
example: https://example.com/receipt/9876543210
nullable: true
required:
- amount
- paymentMethod
- reference
- userFlow
CreatePaymentResponse:
title: Create payment response
description: The `CreatePaymentResponse` object.
type: object
properties:
redirectUrl:
type: string
format: uri
example: https://landing.vipps.no?token=abc123
description: |-
The URL to which the user is redirected when continuing the payment
for `NATIVE_REDIRECT` and `WEB_REDIRECT`. When `userFlow` is `QR`,
a link to the QR image (or the target URL) will be returned.
Nothing will be returned when `userFlow` is `PUSH_MESSAGE`.
reference:
$ref: '#/components/schemas/Reference'
required:
- reference
GetPaymentResponse:
title: Get payment response
description: The `GetPaymentResponse` object.
type: object
x-examples: {}
properties:
aggregate:
$ref: '#/components/schemas/Aggregate'
amount:
$ref: '#/components/schemas/Amount'
state:
$ref: '#/components/schemas/State'
paymentMethod:
$ref: '#/components/schemas/PaymentMethodResponse'
profile:
$ref: '#/components/schemas/ProfileResponse'
pspReference:
$ref: '#/components/schemas/PspReference'
redirectUrl:
type: string
format: uri
example: https://landing.vipps.no?token=abc123
description: >-
The URL you should redirect the user to to continue with the
payment.
This is the URL to the Vipps MobilePay landing page.
See:
https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/
reference:
$ref: '#/components/schemas/Reference'
metadata:
$ref: '#/components/schemas/Metadata'
required:
- aggregate
- amount
- state
- paymentMethod
- profile
- pspReference
- reference
IndustryData:
description: Additional compliance data related to the transaction.
type: object
properties:
airlineData:
$ref: '#/components/schemas/AirlineData'
AirlineData:
title: AirlineData
type: object
required:
- agencyInvoiceNumber
- airlineCode
- airlineDesignatorCode
- passengerName
description: |-
Airline related data.
If present, `passengerName`, `airlineCode`, `airlineDesignatorCode`,
and `agencyInvoiceNumber` are all required.
properties:
agencyInvoiceNumber:
type: string
description: Reference number for the invoice, issued by the agency.
minLength: 1
maxLength: 6
airlineCode:
type: string
description: |-
IATA 3-digit accounting code (PAX); numeric.
It identifies the carrier. eg KLM = 074.
format: IATA 3-digit accounting code (PAX)
example: '074'
minLength: 3
maxLength: 3
airlineDesignatorCode:
type: string
description: |-
IATA 2-letter accounting code (PAX); alphabetical.
It identifies the carrier. Eg KLM = KL.
format: IATA 2-letter airline code
example: KL
minLength: 2
maxLength: 2
passengerName:
type: string
description: Passenger name, initials, and a title.
format: last name + first name or initials + title.
example: FLYER / MARY MS.
minLength: 1
maxLength: 49
ticketNumber:
type: string
description: The ticket's unique identifier.
minLength: 1
maxLength: 150
example: 123-1234567890
Aggregate:
title: Aggregate
type: object
properties:
authorizedAmount:
$ref: '#/components/schemas/Amount'
cancelledAmount:
$ref: '#/components/schemas/Amount'
capturedAmount:
$ref: '#/components/schemas/Amount'
refundedAmount:
$ref: '#/components/schemas/Amount'
required:
- authorizedAmount
- cancelledAmount
- capturedAmount
- refundedAmount
CancelModificationRequest:
title: CancelModificationRequest
type: object
x-examples: {}
properties:
cancelTransactionOnly:
type: boolean
description: >-
Only cancel transaction if it has not been authorized.
If this flag is set and the transaction has been authorized, the
reserved amount will not be canceled.
CaptureModificationRequest:
title: CaptureModificationRequest
type: object
x-examples: {}
properties:
modificationAmount:
$ref: '#/components/schemas/Amount'
required:
- modificationAmount
RefundModificationRequest:
title: RefundModificationRequest
type: object
x-examples: {}
properties:
modificationAmount:
$ref: '#/components/schemas/Amount'
required:
- modificationAmount
ModificationResponse:
title: ModificationResponse
type: object
properties:
amount:
$ref: '#/components/schemas/Amount'
state:
$ref: '#/components/schemas/State'
aggregate:
$ref: '#/components/schemas/Aggregate'
pspReference:
$ref: '#/components/schemas/PspReference'
reference:
$ref: '#/components/schemas/Reference'
required:
- amount
- state
- aggregate
- pspReference
- reference
MSN:
type: string
title: MSNType
pattern: ^[0-9]{4,7}$
minLength: 4
maxLength: 7
example: '1234567'
description: The merchant serial number (MSN) for the sales unit.
Reference:
type: string
title: ReferenceType
description: >-
The `reference` is the unique identifier for the payment, specified when
initiating the payment. The reference must be unique for the sales unit
(MSN), but is not _globally_ unique, so several MSNs may use the same
reference. See the [recommendations](/docs/knowledge-base/orderid/).
pattern: ^[a-zA-Z0-9-]{8,64}$
minLength: 8
maxLength: 64
example: acme-shop-123-order123abc
x-examples: {}
PaymentEventName:
type: string
enum:
- CREATED
- ABORTED
- EXPIRED
- CANCELLED
- CAPTURED
- REFUNDED
- AUTHORIZED
- TERMINATED
example: AUTHORIZED
x-enum-varnames:
- CREATED
- ABORTED
- EXPIRED
- CANCELLED
- CAPTURED
- REFUNDED
- AUTHORIZED
- TERMINATED
PspReference:
type: string
title: PspReference
description: >-
Each payment operation (i.e., create, capture, refund, cancel) will have
a unique `pspReference`, defined by Vipps MobilePay.
One of:
- The *Get event log* response contains each event and its unique
`pspReference` value.
- The *Get payment* response contains the `pspReference` for the payment
creation event.
- The *Adjustment* response, returned by Cancel, Capture, and Refund
requests, contains the `pspReference` for the payment creation event.
example: '3343121302'
Address:
title: Address
type: object
x-examples:
Vipps:
id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
lines:
- Robert Levins gate 5
postCode: '0154'
city: Oslo
country: Norway
properties:
city:
type: string
example: Oslo
country:
type: string
example: 'NO'
pattern: ^[A-Z]{2}$
description: Country code according to ISO 3166-2 (two capital letters).
id:
type: string
format: uuid
description: >-
Unique ID of the address, always provided in response from Vipps
MobilePay.
lines:
type: array
description: Array of addressLines, for example street name, number, etc.
items:
type: string
example: Robert Levins gate 5
postCode:
type: string
description: Postcode of the address in local country format.
example: '0154'
required:
- lines
- postCode
- city
- country
ProfileRequest:
title: Profile
type: object
properties:
scope:
type: string
example: name phoneNumber
description: >-
A space-separated string list of the required user information
(e.g., "name phoneNumber") for the payment, in
accordance with the OpenID Connect specification.
See the
[Userinfo user
guide](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-guide#scope)
for details.
Possible values are:
- name
- address
- email
- phoneNumber
- birthDate
- nin
ProfileResponse:
title: Profile
type: object
properties:
sub:
type: string
description: >-
If `profile.scope` was requested in `createPayment`, this value will
be populated once
`state` is `AUTHORIZED`. This can be used towards the
[Userinfo
endpoint](https://developer.vippsmobilepay.com/api/userinfo#operation/getUserinfo)
to fetch required user data.
PaymentMethod:
title: PaymentMethod
type: object
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
blockedSources:
type: array
items:
$ref: '#/components/schemas/BlockedPaymentSources'
required:
- type
PaymentMethodResponse:
title: PaymentMethodResponse
type: object
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
cardBin:
description: |-
The payment card's Bank Identification Number (BIN), that
identifies which bank has issued the card.
The BIN will be returned, if available.
minLength: 6
maxLength: 6
type: string
example: '540185'
required:
- type
PaymentMethodType:
type: string
enum:
- WALLET
- CARD
example: WALLET
description: >-
The paymentMethod type to be performed.
`WALLET` is a card used in the Vipps or MobilePay app.
`CARD` is free-standing card payments, outside of the Vipps or MobilePay
app.
`CARD` has to be combined with a `userFlow` of `WEB_REDIRECT`,
as the card payment can not be completed in the Vipps or MobilePay app.
BlockedPaymentSources:
type: string
enum:
- COMMERCIAL_CARDS
example: COMMERCIAL_CARDS
description: >-
Payment sources that are eligible for blocking when using `WALLET` as
payment method type. Applies only for Danish and Finnish markets.
PaymentAdjustment:
title: PaymentAdjustment
type: object
properties:
modificationAmount:
$ref: '#/components/schemas/Amount'
modificationReference:
$ref: '#/components/schemas/Reference'
required:
- modificationAmount
- modificationReference
WebhookEvent:
title: WebhookEvent
type: object
x-examples: {}
properties:
msn:
$ref: '#/components/schemas/MSN'
reference:
$ref: '#/components/schemas/Reference'
pspReference:
$ref: '#/components/schemas/PspReference'
name:
$ref: '#/components/schemas/PaymentEventName'
amount:
$ref: '#/components/schemas/Amount'
timestamp:
type: string
format: date-time
example: '2024-12-31T00:00:00Z'
idempotencyKey:
type: string
description: The Idempotency key of the request.
nullable: true
success:
type: boolean
description: |-
The outcome of this payment operation:
`true` means that the operation was successful.
required:
- msn
- reference
- pspReference
- name
- amount
- timestamp
- success
PaymentEvent:
title: PaymentEvent
type: object
x-examples: {}
properties:
reference:
$ref: '#/components/schemas/Reference'
pspReference:
$ref: '#/components/schemas/PspReference'
name:
$ref: '#/components/schemas/PaymentEventName'
amount:
$ref: '#/components/schemas/Amount'
timestamp:
type: string
format: date-time
example: '2022-12-31T00:00:00Z'
idempotencyKey:
type: string
description: |-
The idempotency key of the request.
Specified by the merchant/partner making the API request.
nullable: true
maxLength: 50
example: fb492b5e-7907-4d83-ba20-c7fb60ca35de
success:
type: boolean
description: The outcome of the event
required:
- reference
- pspReference
- paymentAction
- amount
- timestamp
- success
Problem:
title: Problem
description: |-
The standard error object, based on RFC 7808.
See https://developer.vippsmobilepay.com/docs/knowledge-base/errors
type: object
properties:
type:
type: string
format: uri
description: A URI reference that identifies the problem type.
title:
type: string
description: >-
A short, human-readable summary of the problem type. It will not
change from occurrence to occurrence of the problem.
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem.
status:
type: integer
description: The HTTP response code.
traceId:
type: string
description: An id that can be used to facilitate in tracing the error.
extraDetails:
type: array
nullable: true
items:
$ref: '#/components/schemas/ExtraDetail'
required:
- type
- title
- status
- traceId
State:
type: string
title: State
description: >-
The state of the Payment.
One of:
- `CREATED`: The user has not yet acted upon the payment.
Example: The user has received a push message, but not yet opened it.
- `ABORTED`: The user has aborted the payment before authorization. This
is a final state.
Example: The user cancelled instead of accepting the payment.
- `EXPIRED`: The user did not act on the payment within the payment
expiration time. This is a final state.
Example: The user received a push message, but did nothing before the payment request timed out.
- `AUTHORIZED`: The user has approved the payment. This is a final
state.
Example: A payment that has been refunded may have one or more refund events, but the state would be `AUTHORIZED`.
- `TERMINATED`: The merchant has terminated the payment via the
cancelPayment endpoint. This is a final state.
Example: The merchant was not able to provide the product or service, and has cancelled the payment.
enum:
- CREATED
- ABORTED
- EXPIRED
- AUTHORIZED
- TERMINATED
x-enum-varnames:
- CREATED
- ABORTED
- EXPIRED
- AUTHORIZED
- TERMINATED
ExtraDetail:
title: ExtraDetail
type: object
properties:
name:
type: string
reason:
type: string
required:
- name
- reason
ForceApprove:
title: ForceApprove
type: object
properties:
customer:
$ref: '#/components/schemas/Customer'
token:
type: string
description: >-
The token value received in the `redirectUrl` property in the Create
payment response
QuantityUnitEnum:
type: string
title: QuantityUnitEnum
enum:
- PCS
- KG
- KM
- MINUTE
- LITRE
- KWH
description: Available units for quantity. Will default to PCS if not set
default: PCS
nullable: true
UnitInfo:
title: UnitInfo
type: object
description: >-
Optional. If no quantity info is provided the order line will default to
1 pcs
x-examples:
example-1:
value:
quantity: '0.822'
unitPrice: 15000
quantityUnit: KG
example-2:
value:
quantity: '2'
unitPrice: 20000
quantityUnit: PCS
properties:
unitPrice:
type: integer
minimum: 0
format: int64
description: Total price per unit, including tax and excluding discount
nullable: true
quantity:
type: string
maxLength: 10
pattern: ^\d+([\.]\d{1,8})?$
example: '0.822'
description: Quantity given as a integer or fraction (only for cosmetics)
quantityUnit:
$ref: '#/components/schemas/QuantityUnitEnum'
required:
- unitPrice
- quantity
OrderLine:
title: OrderLine
type: object
description: >-
Amounts are specified in minor units (i.e., integers with two trailing
zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
x-examples:
OrderLineExample:
value:
orderLines:
- name: socks
id: line_item_1
totalAmount: 1000
totalAmountExcludingTax: 800
totalTaxAmount: 200
taxPercentage: 25
unitInfo:
unitPrice: 400
quantity: '2.5'
quantityUnit: KG
discount: 0
productUrl: https://example.com/store/socks
- name: flip-flops
id: line_item_2
totalAmount: 5000
totalAmountExcludingTax: 4000
totalTaxAmount: 1000
taxPercentage: 25
unitInfo:
unitPrice: 2500
quantity: '3'
quantityUnit: PCS
discount: 2500
productUrl: https://example.com/store/flipflops
properties:
name:
type: string
description: Name of the product in the order line.
example: socks
id:
type: string
description: The product ID
example: '1234567890'
totalAmount:
type: integer
description: >-
Total amount of the order line, including tax and discount. Amounts
are specified in minor units (i.e., integers with two trailing
zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
example: 1000
format: int64
totalAmountExcludingTax:
type: integer
description: >-
Total amount of order line with discount excluding tax. Amounts are
specified in minor units (i.e., integers with two trailing zeros).
For example: 10.00 EUR/NOK/DKK should be written as 1000.
example: 800
format: int64
totalTaxAmount:
type: integer
description: >-
Total tax amount paid for the order line. Amounts are specified in
minor units (i.e., integers with two trailing zeros). For example:
10.00 EUR/NOK/DKK should be written as 1000.
example: 250
format: int64
taxPercentage:
type: integer
description: >-
Tax percentage for the order line. Between 0-100. Either this or
taxRate must be set.
example: 25
deprecated: true
minimum: 0
maximum: 100
nullable: true
taxRate:
type: integer
description: >-
Tax percentage for the order line, represented with 0.01 decimal
points. 5000 equals 50% . Between 0-10000. Either this or
taxPercentage must be set.
example: 2500
minimum: 0
maximum: 10000
nullable: true
unitInfo:
$ref: '#/components/schemas/UnitInfo'
discount:
type: integer
description: >-
Total discount for the order line. Amounts are specified in minor
units (i.e., integers with two trailing zeros). For example: 1.00
EUR/NOK/DKK should be written as 100.
example: 2000
minimum: 0
format: int64
nullable: true
productUrl:
type: string
description: Optional URL linking back to the product at the merchant.
example: https://example.com/store/socks
nullable: true
isReturn:
type: boolean
example: false
description: >-
Flag for marking the order line as returned. This will make it count
negative towards all the sums in bottomLine.
nullable: true
isShipping:
example: false
type: boolean
description: >-
Flag for marking the order line as a shipping line. This will be
shown differently in the app.
nullable: true
required:
- name
- id
- totalAmount
- totalAmountExcludingTax
- totalTaxAmount
CurrencyEnum:
type: string
title: CurrencyEnum
enum:
- NOK
- DKK
- EUR
description: Currency information
nullable: true
ShippingInfo:
title: ShippingInfo
type: object
description: >-
Deprecated, use a regular orderLine with "isShipping" flag. Using this
will result in faulty calculation of sum and tax.
deprecated: true
properties:
amount:
type: integer
minimum: 0
format: int64
description: Total amount for the shipping, including tax and discount
example: 1000
nullable: true
amountExcludingTax:
type: integer
minimum: 0
format: int64
description: Total amount for shipping excluding tax
example: 1000
nullable: true
taxAmount:
type: integer
minimum: 0
format: int64
description: Total tax amount paid for the shipping
example: 250
nullable: true
taxPercentage:
type: integer
minimum: 0
maximum: 100
description: Tax-percentage for the Shipping
example: 25
nullable: true
required:
- amount
- amountExcludingTax
- taxAmount
- taxPercentage
PaymentSources:
type: object
x-examples:
PaymentSourcesExample:
giftCard: 200
card: 50
voucher: 25
cash: 25
properties:
giftCard:
type: integer
nullable: true
card:
type: integer
nullable: true
voucher:
type: integer
nullable: true
cash:
type: integer
nullable: true
BarcodeFormatEnum:
type: string
title: BarcodeFormatEnum
enum:
- EAN-13
- CODE 39
- CODE 128
nullable: true
Barcode:
title: Barcode
type: object
properties:
format:
$ref: '#/components/schemas/BarcodeFormatEnum'
data:
type: string
nullable: true
required:
- format
- data
BottomLine:
title: BottomLine
type: object
description: >-
Summary of the order. Total amount and total. Amounts are specified in
minor units (i.e., integers with two trailing zeros). For example: 10.00
EUR/NOK/DKK should be written as 1000.
x-examples:
BottomLineExample:
value:
currency: NOK
tipAmount: 0
posId: pos_122
paymentSources:
card: 100
giftCard: 50
barcode:
format: EAN-13
data: '123456'
receiptNumber: '1234567'
properties:
currency:
$ref: '#/components/schemas/CurrencyEnum'
tipAmount:
type: integer
description: >-
Tip amount for the order. Amounts are specified in minor units
(i.e., integers with two trailing zeros). For example: 10.00
EUR/NOK/DKK should be written as 1000.
example: 2000
minimum: 0
format: int64
nullable: true
giftCardAmount:
type: integer
description: Amount paid by gift card or coupon.
example: 20000
minimum: 0
format: int64
deprecated: true
nullable: true
posId:
type: string
description: POS ID is the device number of the POS terminal
nullable: true
totalAmount:
type: integer
description: >-
Deprecated, sum will be calculated based on the sum of the
orderLines
format: int64
deprecated: true
nullable: true
totalTax:
type: integer
description: >-
Deprecated, tax will be calculated based on the sum of the
totalTaxAmount field on each orderLine
minimum: 0
format: int64
deprecated: true
nullable: true
totalDiscount:
type: integer
description: >-
Deprecated, discount will be calculated based on the sum of the
discount field on each orderLine
minimum: 0
format: int64
deprecated: true
nullable: true
shippingAmount:
type: integer
description: >-
Deprecated, use a regular orderLine with "isShipping" flag. Using
this will result in faulty calculation of sum and tax.
minimum: 0
format: int64
deprecated: true
nullable: true
shippingInfo:
$ref: '#/components/schemas/ShippingInfo'
paymentSources:
$ref: '#/components/schemas/PaymentSources'
barcode:
$ref: '#/components/schemas/Barcode'
receiptNumber:
type: string
nullable: true
terminalId:
type: string
description: Deprecated, use "posId" instead.
nullable: true
deprecated: true
required:
- currency
Receipt:
title: Receipt
type: object
x-examples:
ReceiptExample:
orderLines:
- name: socks
id: '1234567890'
totalAmount: 1000
totalAmountExcludingTax: 800
totalTaxAmount: 200
taxPercentage: 25
unitInfo:
unitPrice: 0
quantity: '0.822'
quantityUnit: PCS
discount: 0
productUrl: https://example.com/store/socks
isReturn: false
isShipping: false
bottomLine:
tipAmount: 0
currency: NOK
posId: string
paymentSources:
giftCard: 0
card: 0
voucher: 0
cash: 0
barcode:
format: EAN-13
data: '123456'
receiptNumber: '1234567'
properties:
orderLines:
type: array
description: >-
Amounts are specified in minor units (i.e., integers with two
trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as
1000.
minItems: 1
items:
$ref: '#/components/schemas/OrderLine'
bottomLine:
$ref: '#/components/schemas/BottomLine'
required:
- orderLines
- bottomLine
parameters:
Merchant-Serial-Number:
name: Merchant-Serial-Number
in: header
required: true
schema:
$ref: '#/components/schemas/MSN'
APIM-Subscription-Key:
name: Ocp-Apim-Subscription-Key
in: header
required: true
schema:
type: string
example: da7d5b0e18a84aeda961c0c31b75c2a9
description: |-
The subscription key for a sales unit.
See [API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys/).
Vipps-System-Name:
name: Vipps-System-Name
in: header
description: >-
The name of the ecommerce solution.
One word in lowercase letters is good.
See
[http-headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: WooCommerce
Vipps-System-Version:
name: Vipps-System-Version
in: header
description: >-
The version number of the ecommerce solution.
See
[http-headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: 5.4.0
Vipps-System-Plugin-Name:
name: Vipps-System-Plugin-Name
in: header
description: >-
The name of the ecommerce plugin (if applicable).
One word in lowercase letters is good.
See
[http-headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: woocommerce-payment
Vipps-System-Plugin-Version:
name: Vipps-System-Plugin-Version
in: header
description: >-
The version number of the ecommerce plugin (if applicable).
See
[http-headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: 1.2.1
Payment-Reference-ID:
name: Reference
in: path
required: true
schema:
$ref: '#/components/schemas/Reference'
Idempotency-Key:
name: Idempotency-Key
in: header
required: true
schema:
type: string
maxLength: 50
description: >-
Idempotency key for the request, ensures idempotent actions.
See
[idempotency](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers#idempotency)
example: fb492b5e-7907-4d83-ba20-c7fb60ca35de
securitySchemes:
Bearer-Authorization:
name: Authorization
type: apiKey
in: header
description: >-
The access token is a base64-encoded string that is required for all API
calls.
It is a JWT (JSON Web Token). The access token is fetched from the
[`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost)
endpoint.
It is valid for 1 hour in the test environment and 24 hours in the
production environment.
responses:
GetPaymentResponse:
description: Get Payment response
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentResponse'
CreatePaymentResponse:
description: Create Payment response
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponse'
examples:
UrlRedirect:
value:
redirectUrl: >-
https://landing.vipps.no?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni
reference: acme-shop-123-order123abc
QrImageUrl:
value:
redirectUrl: >-
https://qr-image.vipps.no/v1?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni
reference: acme-shop-123-order123abc
NativeRedirect:
value:
redirectUrl: vipps://token=abc123
reference: racme-shop-123-order123abc
PushFlow:
value:
reference: acme-shop-123-order123abc
AdjustResponse:
description: Adjustment response
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ModificationResponse'
headers: {}
ProblemResponse:
description: Standard problem response.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
headers: {}
examples: {}
security:
- Bearer-Authorization: []
Raw
recurring-swagger-id.yaml
openapi: 3.0.0
info:
description: >-
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](https://developer.vippsmobilepay.com/docs/APIs/recurring-api).
version: 3.1.1
title: Recurring Payments Merchant API
servers:
- url: https://api.vipps.no
description: >-
Production environment (uses the production API keys, the official app and
live data)
- url: https://apitest.vipps.no
description: Test environment (uses the test API keys, the test app and test data)
tags:
- name: Agreement v3 endpoints
- name: Charge v3 endpoints
paths:
/recurring/v3/agreements:
get:
tags:
- Agreement v3 endpoints
summary: List Agreements
description: >-
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.
operationId: ListAgreementsV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementStatusQuery'
- $ref: '#/components/parameters/CreatedAfterQuery'
- $ref: '#/components/parameters/PageNumberQuery'
- $ref: '#/components/parameters/PageSizeQuery'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgreementResponseV3'
deprecated: false
post:
tags:
- Agreement v3 endpoints
summary: Create a new Agreement, to be confirmed in the Vipps or MobilePay app
description: >-
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.
operationId: DraftAgreementV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DraftAgreementV3'
examples:
Minimal:
description: Agreement with a set price and interval.
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
With Initial Charge:
description: >-
If you want the customer to pay to activate the agreement, you
should add an initial charge. If the amount on the initial
charge is not the same as the agreement/campaign price, it
will show up as a separate payment bubble in the app.
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
initialCharge:
amount: 100
currency: NOK
description: Initial Charge
transactionType: DIRECT_CAPTURE
With Price Campaign:
description: >-
A price campaign allows you to communicate that the agreement
price is rebated until a given date, ie. "1kr per week until
04.05.2022, then 39 per week".
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
campaign:
type: PRICE_CAMPAIGN
price: 100
end: 2022/02/28T00:00:00Z
With Period Campaign:
description: >-
A period campaign allows you to communicate a campaign where
the user pays a fixed price for a given period before the
normal agreement starts, ie. "4 weeks for 1 kr". Should be
combined with an initial charge to get money on activation.
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
campaign:
type: PERIOD_CAMPAIGN
price: 100
period:
unit: WEEK
count: 4
initialCharge:
amount: 100
currency: NOK
description: Activation Charge
transactionType: DIRECT_CAPTURE
With Event Campaign:
description: >-
A period campaign allows you to communicate a campaign where
the user pays a fixed price until a given event before the
normal agreement starts, ie. "until Christmas for 1 kr".
Should be combined with an initial charge to get money on
activation.
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
campaign:
type: EVENT_CAMPAIGN
price: 100
eventDate: 2022/12/25T00:00:00Z
eventText: until Christmas
initialCharge:
amount: 100
currency: NOK
description: Activation Charge
transactionType: DIRECT_CAPTURE
With Variable Amount:
description: >-
An agreement where the price can vary and the user choose a
max amount they can be charged each interval.
value:
pricing:
type: VARIABLE
suggestedMaxAmount: 3000
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
With Flexible pricing:
description: An agreement where the price can vary.
value:
pricing:
type: FLEXIBLE
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
With Profile Flow:
description: >-
User consents to sharing data that can be retrieved after they
accept the agreement.
value:
pricing:
type: LEGACY
amount: 2500
currency: NOK
interval:
unit: MONTH
count: 1
merchantRedirectUrl: https://example.com/redirect
merchantAgreementUrl: https://example.com/agreement
phoneNumber: '4712345678'
productName: MyNews Digital
scope: address name email birthDate phoneNumber
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/DraftAgreementResponseV3'
'400':
$ref: '#/components/responses/ErrorResponseV3'
'403':
$ref: '#/components/responses/ErrorResponseV3'
'409':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/{agreementId}:
get:
tags:
- Agreement v3 endpoints
summary: Fetch an Agreement
description: >-
Fetch a single agreement for a user.
Recommended to use when polling for status changes after sending an
agreement to a user.
operationId: FetchAgreementV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
patch:
tags:
- Agreement v3 endpoints
summary: Update an Agreement
description: >-
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.
operationId: UpdateAgreementPatchV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
requestBody:
description: agreement
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchAgreementV3'
responses:
'202':
description: >-
Accepted. Request accepted, the action will likely succeed but has
not yet been enacted.
'204':
description: No content
'400':
$ref: '#/components/responses/ErrorResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/{agreementId}/accept:
patch:
tags:
- Agreement v3 endpoints
summary: Force accept an Agreement (Only available in test environment)
description: |-
Forces an agreement to be accepted by the given customer phone number.
This endpoint can only be used in the test environment.
operationId: acceptUsingPATCHV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ForceAcceptAgreementV3'
responses:
'204':
description: OK
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/ErrorResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/{agreementId}/charges:
get:
tags:
- Charge v3 endpoints
summary: List Charges
description: >-
Fetches all charges for a single agreement, including the optional
initial charge.
Supports filtering on status using query parameter.
operationId: ListChargesV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Continuation-Token'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
- $ref: '#/components/parameters/ChargeStatusQueryV3'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChargeResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
post:
tags:
- Charge v3 endpoints
summary: Create a new charge
description: >-
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`.
operationId: CreateChargeV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeV3'
examples:
Recurring:
value:
amount: 49900
transactionType: DIRECT_CAPTURE
description: October
due: '2018-10-01'
retryDays: 5
type: RECURRING
Unscheduled:
value:
amount: 49900
transactionType: DIRECT_CAPTURE
description: October
type: UNSCHEDULED
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeReference'
'400':
$ref: '#/components/responses/ErrorResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
'409':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/charges:
post:
tags:
- Charge v3 endpoints
summary: Create multiple charges
description: >-
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.
operationId: CreateChargeAsyncV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CreateChargeAsyncV3'
responses:
'202':
description: None, some or all charges passed API level validation.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncChargeResponse'
/recurring/v3/agreements/{agreementId}/charges/{chargeId}:
get:
tags:
- Charge v3 endpoints
summary: Fetch a charge
description: Fetch a single charge for a user.
operationId: FetchChargeV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
- $ref: '#/components/parameters/ChargeId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
delete:
tags:
- Charge v3 endpoints
summary: Cancel a charge
description: >-
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.
operationId: CancelChargeV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
- $ref: '#/components/parameters/ChargeId'
responses:
'202':
description: >-
Accepted. Request accepted, the action will likely succeed but has
not yet been enacted.
'204':
description: No content
'400':
$ref: '#/components/responses/ErrorResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
'409':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/charges/{chargeId}:
get:
tags:
- Charge v3 endpoints
summary: Fetch a charge by ID
description: >-
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}`.
operationId: FetchChargeByIdV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/ChargeId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture:
post:
tags:
- Charge v3 endpoints
summary: Capture a reserved charge
description: |-
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).
operationId: CaptureChargeV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
- $ref: '#/components/parameters/ChargeId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CaptureRequestV3'
responses:
'202':
description: >-
Accepted. Request accepted, the action will likely succeed but has
not yet been enacted.
'204':
description: No content
'400':
$ref: '#/components/responses/ErrorResponseV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
'409':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
/recurring/v3/agreements/{agreementId}/charges/{chargeId}/refund:
post:
tags:
- Charge v3 endpoints
summary: Refund a charge
description: >-
Refunds a charge, can also do a partial refund (refunding a smaller part
of the payment).
operationId: RefundChargeV3
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
- $ref: '#/components/parameters/Idempotency-Key'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Merchant-Serial-Number'
- $ref: '#/components/parameters/Vipps-System-Name'
- $ref: '#/components/parameters/Vipps-System-Version'
- $ref: '#/components/parameters/Vipps-System-Plugin-Name'
- $ref: '#/components/parameters/Vipps-System-Plugin-Version'
- $ref: '#/components/parameters/AgreementId'
- $ref: '#/components/parameters/ChargeId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequest'
responses:
'204':
description: No content
'400':
$ref: '#/components/schemas/ErrorV3'
'404':
$ref: '#/components/responses/ErrorResponseV3'
'409':
$ref: '#/components/responses/ErrorResponseV3'
deprecated: false
components:
parameters:
AgreementId:
name: agreementId
in: path
required: true
description: The agreement identifier (ID)
schema:
type: string
example: agr_5kSeqz
ChargeId:
name: chargeId
in: path
required: true
description: The charge identifier (ID)
schema:
type: string
example: chr-123ab
Ocp-Apim-Subscription-Key:
in: header
name: Ocp-Apim-Subscription-Key
description: >-
The subscription key for your sales unit. See [API
keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys/).
Keep it secret.
required: true
schema:
type: string
example: 0f14ebcab0ec4b29ae0cb90d91b4a84a
Authorization:
in: header
name: Authorization
description: >-
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`](https://developer.vippsmobilepay.com/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost)
endpoint.
It is valid for 1 hour in the test environment and 24 hours in the
production environment.
required: true
schema:
type: string
Idempotency-Key:
in: header
name: Idempotency-Key
description: |-
An Idempotency key must be provided to ensure idempotent requests.
Key size can be between 1 to 40 characters.
Key must not contain '#', '?', '/' or '\\'
required: true
schema:
type: string
Continuation-Token:
in: header
name: Continuation-Token
description: >-
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.
required: false
schema:
type: string
format: uuid
Merchant-Serial-Number:
name: Merchant-Serial-Number
in: header
description: |-
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.
schema:
type: string
example: 123456
AgreementStatusQuery:
in: query
name: status
required: false
description: Filter by the `status` of the agreement.
schema:
$ref: '#/components/schemas/AgreementStatus'
CreatedAfterQuery:
in: query
name: createdAfter
required: false
description: Filter by createdAfter timestamp (in milliseconds) for paginating.
schema:
type: integer
format: int64
example: 1644572442944
ChargeStatusQuery:
in: query
name: chargeStatus
required: false
description: Filter by status of the charge.
schema:
$ref: '#/components/schemas/ChargeStatus'
ChargeStatusQueryV3:
in: query
name: status
required: false
description: Filter by status of the charge.
schema:
$ref: '#/components/schemas/ChargeStatus'
PageNumberQuery:
in: query
name: pageNumber
required: false
description: >-
Page number for paginating (should be used in combination with
pageSize).
schema:
type: integer
format: int32
minimum: 1
example: 1
PageSizeQuery:
in: query
name: pageSize
required: false
description: Page size for paginating (must be used in combination with pageNumber).
schema:
type: integer
format: int32
minimum: 1
maximum: 2000
default: 500
example: 500
Vipps-System-Name:
name: Vipps-System-Name
in: header
description: >-
The name of the ecommerce solution. One word in lowercase letters is
good.
See [HTTP
headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: woocommerce
Vipps-System-Version:
name: Vipps-System-Version
in: header
description: >-
The version number of the ecommerce solution.
See [HTTP
headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: '5.4'
Vipps-System-Plugin-Name:
name: Vipps-System-Plugin-Name
in: header
description: >-
The name of the ecommerce plugin (if applicable). One word in lowercase
letters is good.
See [HTTP
headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: vipps-woocommerce
Vipps-System-Plugin-Version:
name: Vipps-System-Plugin-Version
in: header
description: >-
The version number of the ecommerce plugin (if applicable).
See [HTTP
headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
schema:
type: string
maxLength: 30
example: 1.2.1
Content-Type:
in: header
name: Content-Type
description: The content type must be `application/json`
schema:
type: string
example: application/json
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer 'auth token', from
[`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost)
endpoint.
bearerFormat: JWT
schemas:
AgreementStatus:
type: string
description: Status of the agreement.
default: ACTIVE
example: ACTIVE
enum:
- PENDING
- ACTIVE
- STOPPED
- EXPIRED
ChargeStatus:
type: string
example: PENDING
enum:
- PENDING
- DUE
- RESERVED
- CHARGED
- PARTIALLY_CAPTURED
- FAILED
- CANCELLED
- PARTIALLY_REFUNDED
- REFUNDED
- PROCESSING
ChargeSummary:
type: object
description: A summary of the amounts captured, refunded and cancelled
required:
- captured
- refunded
- cancelled
properties:
captured:
type: integer
format: int32
example: 19900
description: >-
The total amount which has been captured/charged, in case of status
charged/partial capture.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
refunded:
type: integer
format: int32
example: 0
description: >-
The total amount which has been refunded, in case of status
refund/partial refund.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
cancelled:
type: integer
format: int32
example: 19900
description: >-
The total amount which has been cancelled.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
ChargeHistory:
type: array
items:
$ref: '#/components/schemas/ChargeEvent'
description: List of events related to the charge.
ChargeEvent:
type: object
description: Describes the operation that was performed on the charge
required:
- occurred
- event
- amount
- idempotencyKey
- success
properties:
occurred:
type: string
format: date-time
description: >-
Date and time of the event, as timestamp on the format
`yyyy-MM-dd'T'HH:mm:ss'Z'`,
with or without milliseconds.
example: '2022-09-05T14:25:55Z'
event:
type: string
enum:
- CREATE
- RESERVE
- CAPTURE
- REFUND
- CANCEL
- FAIL
example: RESERVE
amount:
type: integer
format: int32
example: 19900
description: >-
The amount related to the operation.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
idempotencyKey:
type: string
description: The idempotency key of the event
success:
type: boolean
description: True if the operation was successful, false otherwise
Currency:
type: string
description: 'ISO-4217: https://www.iso.org/iso-4217-currency-codes.html'
default: NOK
enum:
- NOK
minLength: 3
maxLength: 3
pattern: ^[A-Z]{3}$
example: NOK
PricingTypeV3:
type: string
description: The type of pricing. This decides which properties are required.
enum:
- FLEXIBLE
- LEGACY
- VARIABLE
example: LEGACY
CurrencyV3:
type: string
description: Available types of currency are NOK, EUR and DKK
enum:
- NOK
- EUR
- DKK
minLength: 3
maxLength: 3
pattern: ^[A-Z]{3}$
example: NOK
CountryCode:
type: string
example: 'NO'
pattern: ^[A-Z]{2}$
enum:
- 'NO'
- DK
- FI
description: >-
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.
transactionType:
type: string
description: Type of transaction, either direct capture or reserve capture
enum:
- DIRECT_CAPTURE
- RESERVE_CAPTURE
example: DIRECT_CAPTURE
ProcessingMode:
type: string
description: >-
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.
enum:
- MULTIPLE_ATTEMPTS
- SINGLE_ATTEMPT
example: MULTIPLE_ATTEMPTS
ChargeTypeV3:
type: string
default: RECURRING
enum:
- INITIAL
- RECURRING
- UNSCHEDULED
example: RECURRING
ChargeCreationTypeV3:
type: string
default: RECURRING
enum:
- RECURRING
- UNSCHEDULED
example: RECURRING
Interval:
type: string
description: Interval for subscription
default: MONTH
pattern: ^(YEAR|MONTH|WEEK|DAY)$
enum:
- YEAR
- MONTH
- WEEK
- DAY
example: MONTH
DraftAgreementV3:
title: DraftAgreement
type: object
required:
- pricing
- merchantRedirectUrl
- productName
properties:
campaign:
$ref: '#/components/schemas/campaignV3'
pricing:
$ref: '#/components/schemas/PricingRequestV3'
phoneNumber:
type: string
nullable: true
description: |-
Customers phone number (if available). Used to simplify the
following interaction. MSISDN: https://en.wikipedia.org/wiki/MSISDN
maxLength: 15
example: '4712345678'
initialCharge:
$ref: '#/components/schemas/InitialChargeV3'
interval:
$ref: '#/components/schemas/TimePeriod'
isApp:
type: boolean
description: >-
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](https://developer.vippsmobilepay.com/docs/knowledge-base/app-flow)
example: false
default: false
merchantAgreementUrl:
type: string
maxLength: 1024
description: >-
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](https://developer.vippsmobilepay.com/docs/APIs/login-api),
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.
example: https://example.com/vipps-subscriptions/1234/
merchantRedirectUrl:
type: string
maxLength: 2048
description: |-
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)
example: https://example.com/redirect
productName:
type: string
description: Product name (short)
maxLength: 45
example: Premier League subscription
productDescription:
type: string
description: Product description (longer)
maxLength: 100
scope:
type: string
description: >
Space-separated list of the required user information (e.g., "name
phoneNumber")
for the agreement. See the
[Userinfo user
guide](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-guide#scope)
for details.
Possible values are:
- name
- address
- email
- phoneNumber
- birthDate
- nin
example: address name email birthDate phoneNumber
skipLandingPage:
type: boolean
description: >-
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](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page)
default: false
example: false
externalId:
type: string
nullable: true
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
countryCode:
$ref: '#/components/schemas/CountryCode'
DraftAgreementResponseV3:
title: DraftAgreementResponse
type: object
required:
- agreementId
- uuid
properties:
agreementId:
type: string
description: >-
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.
example: agr_5kSeqz
uuid:
type: string
format: uuid
pattern: >-
^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: UUID (RFC 4122) representation of agreementId
example: 9c2ca95c-245f-4a2e-aab2-4a08eb78e6fb
vippsConfirmationUrl:
type: string
description: >-
The `vippsConfirmationUrl` should be used to redirect the
user to the Vipps MobilePay landing page in a desktop flow (with
`https://`),
or to the Vipps or MobilePay app in a mobile flow (with `vipps://`),
where the
user can then approve the agreement.
example: https://api.vipps.no/v2/register/U6JUjQXq8HQmmV
chargeId:
type: string
nullable: true
description: >-
The Id of the initialCharge if given, otherwise `null`.
If an `orderId` is specified this is used as the `chargeId`
otherwise it is auto generated.
example: chr_5kSeqz
pattern: ^[a-zA-Z0-9-]{1,50}$
AgreementResponseV3:
title: Agreement response
type: object
required:
- id
- interval
- pricing
- productName
- uuid
- countryCode
- created
- merchantAgreementUrl
- merchantRedirectUrl
properties:
campaign:
$ref: '#/components/schemas/campaignResponseV3'
nullable: true
pricing:
$ref: '#/components/schemas/PricingResponseV3'
id:
type: string
example: agr_DdLnJAF
maxLength: 36
description: Uniquely identifies this agreement
interval:
$ref: '#/components/schemas/TimePeriodResponse'
productName:
type: string
description: Product name (short)
maxLength: 45
example: Premier League subscription
productDescription:
type: string
description: Product description (longer)
maxLength: 100
created:
type: string
format: date-time
description: |-
Date when agreement was created, in ISO 8601 format.
This is when the agreement was initiated with the API.
example: '2019-01-01T00:00:00Z'
start:
type: string
format: date-time
description: |-
Date and time when agreement was started, in ISO 8601 format.
This is when the agreement was activated.
example: '2019-01-01T00:00:00Z'
nullable: true
stop:
type: string
format: date-time
description: Date and time when agreement was stopped, in ISO 8601 format.
nullable: true
example: null
status:
$ref: '#/components/schemas/AgreementStatus'
merchantAgreementUrl:
type: string
description: >-
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](https://developer.vippsmobilepay.com/docs/APIs/login-api)
We do not have any specific requirements for the security of the
page other than requiring HTTPS.
example: https://example.com/vipps-subscriptions/1234/
merchantRedirectUrl:
type: string
maxLength: 1024
description: |-
URL where customer should be redirected after the agreement has been
approved/rejected in the Vipps or MobilePay app.
HTTPS and deeplinks are allowed (example: myApp://home)
example: https://example.com/landing
sub:
type: string
example: 8d7de74e-0243-11eb-adc1-0242ac120002
description: >-
User identifier (subject). Will be null if profile data was not
requested.
nullable: true
userinfoUrl:
type: string
example: >-
https://api.vipps.no/vipps-userinfo-api/userinfo/8d7de74e-0243-11eb-adc1-0242ac120002
description: >-
The full path of the URL for the userinfo endpoint where the user
data can be retrieved.:
[`GET:/vipps-userinfo-api/userinfo/{sub}`](https://developer.vippsmobilepay.com/api/userinfo#operation/getUserinfo).
This will be null if profile data was not requested.
nullable: true
externalId:
type: string
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
countryCode:
$ref: '#/components/schemas/CountryCode'
uuid:
type: string
format: uuid
pattern: >-
^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
description: UUID (RFC 4122) representation of ID
example: 9c2ca95c-245f-4a2e-aab2-4a08eb78e6fb
vippsConfirmationUrl:
type: string
description: >-
The `vippsConfirmationUrl` should be used to redirect the
user to the Vipps MobilePay landing page in a desktop flow (with
`https://`),
or to the Vipps or MobilePay app in a mobile flow (with `vipps://`),
where the
user can then approve the agreement.
example: https://api.vipps.no/v2/register/U6JUjQXq8HQmmV
PatchAgreementV3:
title: PatchAgreement
type: object
properties:
productName:
type: string
example: Pluss-abonnement
description: Name of the product being subscribed to.
maxLength: 45
productDescription:
type: string
description: Product description (longer)
maxLength: 100
merchantAgreementUrl:
type: string
maxLength: 1024
description: >-
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](https://developer.vippsmobilepay.com/docs/APIs/login-api)
We do not have any specific requirements for the security of the
page other than requiring HTTPS.
example: https://example.com/vipps-subscriptions/1234/
externalId:
type: string
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
status:
type: string
example: STOPPED
description: Status of the agreement.
enum:
- STOPPED
pricing:
$ref: '#/components/schemas/PricingUpdateRequest'
interval:
type: object
description: >-
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.
properties:
type:
type: string
default: RECURRING
enum:
- RECURRING
- FLEXIBLE
example: RECURRING
period:
$ref: '#/components/schemas/TimePeriod'
AgreementReference:
type: object
title: Agreement reference
required:
- agreementId
properties:
agreementId:
type: string
example: agr_asdf123
description: >-
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.
campaignV3:
oneOf:
- $ref: '#/components/schemas/priceCampaignV3'
- $ref: '#/components/schemas/periodCampaignV3'
- $ref: '#/components/schemas/eventCampaignV3'
priceCampaignV3:
title: Price campaign
type: object
nullable: true
required:
- type
- price
- end
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PRICE_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
end:
type: string
example: '2019-06-01T00:00:00Z'
description: |-
The date and time the campaign ends.
Needs to be UTC.
periodCampaignV3:
title: Period campaign
type: object
nullable: true
required:
- type
- price
- period
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PERIOD_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
period:
$ref: '#/components/schemas/TimePeriod'
eventCampaignV3:
title: Event campaign
type: object
nullable: true
required:
- type
- price
- eventText
- eventDate
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- EVENT_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
eventDate:
type: string
format: date-time
example: '2022-12-31T00:00:00Z'
description: The date and time the campaign ends. Must be UTC.
eventText:
type: string
minLength: 1
maxLength: 15
example: until Christmas
description: A short text that describes the event
campaignResponseV3:
oneOf:
- $ref: '#/components/schemas/priceCampaignResponseV3'
- $ref: '#/components/schemas/periodCampaignResponseV3'
- $ref: '#/components/schemas/eventCampaignResponseV3'
- $ref: '#/components/schemas/legacyCampaignResponseV3'
priceCampaignResponseV3:
title: Price Campaign
type: object
required:
- type
- price
- end
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PRICE_CAMPAIGN
- PERIOD_CAMPAIGN
- EVENT_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
end:
type: string
format: date-time
example: '2022-12-31T00:00:00Z'
description: The date and time the campaign ends. Must be UTC.
explanation:
type: string
example: Ordinary price 399 kr starts 6/12/2022
description: >-
The text displayed in the Vipps or MobilePay app to explain the
campaign to the user
periodCampaignResponseV3:
title: Period Campaign
type: object
required:
- type
- price
- end
- period
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PRICE_CAMPAIGN
- PERIOD_CAMPAIGN
- EVENT_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
end:
type: string
example: '2019-06-01T00:00:00Z'
description: |-
The date and time the campaign ends.
Needs to be UTC.
period:
$ref: '#/components/schemas/TimePeriod'
explanation:
type: string
example: Ordinary price 399 kr starts 6/12/2022
description: >-
The text displayed in the Vipps or MobilePay app to explain the
campaign to the user
eventCampaignResponseV3:
title: Event Campaign
type: object
required:
- type
- price
- eventText
- eventDate
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PRICE_CAMPAIGN
- PERIOD_CAMPAIGN
- EVENT_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
eventDate:
type: string
format: date-time
example: '2022-12-31T00:00:00Z'
description: The date and time the campaign ends. Must be UTC.
eventText:
type: string
example: until Christmas
description: A short text that describes the event
explanation:
type: string
example: Ordinary price 399 kr starts 6/12/2022
description: >-
The text displayed in the Vipps or MobilePay app to explain the
campaign to the user
legacyCampaignResponseV3:
title: Legacy Campaign
type: object
required:
- type
- price
- end
properties:
type:
type: string
description: The type of campaign. This decides which properties are required
enum:
- PRICE_CAMPAIGN
- PERIOD_CAMPAIGN
- EVENT_CAMPAIGN
- LEGACY_CAMPAIGN
price:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement in the discount period. The lowering of
the price will be displayed in-app.
Price is specified in minor units.
NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.
end:
type: string
example: '2019-06-01T00:00:00Z'
description: |-
The date and time the campaign ends.
Needs to be UTC.
explanation:
type: string
example: Ordinary price 399 kr starts 6/12/2022
description: >-
The text displayed in the Vipps or MobilePay app to explain the
campaign to the user
PricingRequestV3:
oneOf:
- $ref: '#/components/schemas/LegacyPricingRequestV3'
- $ref: '#/components/schemas/VariablePricingRequestV3'
- $ref: '#/components/schemas/FlexiblePricingRequestV3'
discriminator:
propertyName: type
LegacyPricingRequestV3:
title: LegacyPricingRequestV3
type: object
required:
- type
- currency
- amount
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
amount:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
FlexiblePricingRequestV3:
title: FlexiblePricingRequestV3
type: object
required:
- type
- currency
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
VariablePricingRequestV3:
title: VariablePricingRequestV3
type: object
required:
- type
- currency
- suggestedMaxAmount
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
suggestedMaxAmount:
type: integer
format: int32
example: 30000
description: >-
The suggested max amount that the customer should choose.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
PricingResponseV3:
oneOf:
- $ref: '#/components/schemas/LegacyPricingResponseV3'
- $ref: '#/components/schemas/VariablePricingResponseV3'
- $ref: '#/components/schemas/FlexiblePricingResponseV3'
discriminator:
propertyName: type
LegacyPricingResponseV3:
title: LegacyPricingResponseV3
type: object
required:
- type
- currency
- amount
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
amount:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
FlexiblePricingResponseV3:
title: FlexiblePricingResponseV3
type: object
required:
- type
- currency
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
VariablePricingResponseV3:
title: VariablePricingResponseV3
type: object
required:
- type
- currency
- suggestedMaxAmount
properties:
type:
$ref: '#/components/schemas/PricingTypeV3'
currency:
$ref: '#/components/schemas/CurrencyV3'
suggestedMaxAmount:
type: integer
format: int32
example: 30000
description: >-
The suggested max amount that the customer should choose
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
maxAmount:
type: integer
format: int32
example: 30000
description: The max amount chosen by the customer.
PricingUpdateRequest:
title: UpdateAgreementPricingRequest
type: object
properties:
amount:
type: integer
format: int32
example: 1500
description: >-
The price of the agreement, can only be updated if agreement type is
LEGACY.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
suggestedMaxAmount:
type: integer
format: int32
example: 3000
description: >-
The suggested max amount that the customer should choose, required
if type is VARIABLE.
There are limits for each currency.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
InitialChargeV3:
title: InitialCharge
description: >-
An initial charge for a new agreement.
The charge will be processed immediately when the user approves the
agreement.
type: object
required:
- amount
- description
- transactionType
properties:
amount:
type: integer
format: int32
example: 19900
description: >-
The amount that must be paid or approved before starting the
agreement.
Amounts are specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
description:
type: string
minLength: 1
maxLength: 100
example: Månedsabonnement
description: This field is visible to the end user in-app
transactionType:
type: string
example: DIRECT_CAPTURE
description: The type of payment to be made.
enum:
- RESERVE_CAPTURE
- DIRECT_CAPTURE
orderId:
type: string
example: acme-shop-123-order123abc
description: >-
An optional, but recommended `orderId` for the charge.
If provided, this will be the `chargeId` for this charge.
See: [orderid
recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/)
If no `orderId` is specified, the `chargeId` will be automatically
generated.
externalId:
type: string
description: |-
An optional external ID for the charge
The `externalId` can be used by the merchant to map the `chargeId`
to an ID in a subscription system or similar.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
CreateChargeV3:
title: CreateCharge
type: object
required:
- amount
- description
- transactionType
properties:
amount:
type: integer
format: int32
example: 19900
description: >-
Amount to be paid by the customer, specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
transactionType:
$ref: '#/components/schemas/transactionType'
type:
$ref: '#/components/schemas/ChargeCreationTypeV3'
description:
type: string
minLength: 1
maxLength: 100
example: Månedsabonnement
description: This field is visible to the end user in-app
due:
type: string
description: >-
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
example: '2030-12-31'
retryDays:
type: integer
format: int32
minimum: 0
maximum: 14
example: 5
description: >-
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:
$ref: '#/components/schemas/ProcessingMode'
orderId:
type: string
maxLength: 50
minLength: 1
pattern: ^[a-zA-Z\d-]+
example: acme-shop-123-order123abc
description: >-
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](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/)
If no `orderId` is specified, the `chargeId` will be automatically
generated.
externalId:
type: string
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
CreateChargeAsyncV3:
title: CreateChargeAsync
type: object
required:
- agreementId
- amount
- description
- due
- retryDays
- transactionType
- orderId
properties:
agreementId:
type: string
example: agr_asdf123
description: >-
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:
type: integer
format: int32
example: 19900
description: >-
Amount to be paid by the customer, specified in minor units
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
transactionType:
$ref: '#/components/schemas/transactionType'
description:
type: string
minLength: 1
maxLength: 100
example: Månedsabonnement
description: This field is visible to the end user in-app
due:
type: string
description: >-
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.
example: '2030-12-31'
retryDays:
type: integer
format: int32
minimum: 0
maximum: 14
example: 5
description: >-
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:
$ref: '#/components/schemas/ProcessingMode'
orderId:
type: string
maxLength: 50
minLength: 1
pattern: ^[a-zA-Z\d-]+
example: acme-shop-123-order123abc
description: >-
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](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid/)
externalId:
type: string
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
AsyncChargeResponse:
title: AsyncChargeResponse
type: object
required:
- invalidCharges
- validCharges
properties:
invalidCharges:
type: array
items:
$ref: '#/components/schemas/InvalidChargeResponse'
validCharges:
type: array
items:
type: string
example:
- chr_1111
- chr_2222
InvalidChargeResponse:
title: ChargeBatchResponse
type: object
required:
- chargeBatchItemDto
- errors
properties:
chargeBatchItemDto:
$ref: '#/components/schemas/ChargeBatchItemDto'
errors:
type: array
items:
type: string
ChargeBatchItemDto:
title: ChargeBatchItemDto
type: object
required:
- due
- retryDays
- amount
- description
- transactionType
- orderId
properties:
due:
type: string
example: '2024-02-09'
retryDays:
type: integer
format: int32
example: 3
processingMode:
type: string
enum:
- MULTIPLE_ATTEMPTS
- SINGLE_ATTEMPT
example: MULTIPLE_ATTEMPTS
amount:
type: integer
format: int32
example: 300
description:
type: string
example: charge description
transactionType:
type: string
enum:
- DIRECT_CAPTURE
- RESERVE_CAPTURE
example: DIRECT_CAPTURE
orderId:
type: string
maxLength: 50
minLength: 1
pattern: ^[a-zA-Z\d-]+
example: ea929435-d761-4a80-9271-c896d131b796
agreementId:
type: string
externalId:
type: string
ChargeReference:
type: object
title: Charge reference
properties:
chargeId:
type: string
example: chg_WCVbcAbRCmu2zk
description: Unique identifier for this charge, up to 15 characters.
maxLength: 15
ChargeResponseV3:
title: ChargeResponse
type: object
required:
- transactionId
- description
- type
- transactionType
- amount
- summary
- history
- due
- id
- status
- currency
- agreementId
- externalId
- retryDays
- processingMode
properties:
amount:
type: integer
format: int32
example: 19900
description: >-
Amount to be paid by the customer, specified in minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
currency:
$ref: '#/components/schemas/CurrencyV3'
description:
type: string
description: Description of the charge
example: 'Premier League subscription: September'
due:
type: string
format: date-time
description: The due date for this charge
example: '2019-06-01T00:00:00Z'
id:
type: string
description: Identifier for this charge (for this customer's subscription).
maxLength: 15
example: chr_WCVbcA
agreementId:
type: string
description: Id of the agreement the charge belongs to
example: agr_5kSeqz
externalId:
type: string
description: |-
An optional external ID for the charge
The `externalId` can be used by the merchant to map the `chargeId`
to an ID in a subscription system or similar.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
externalAgreementId:
type: string
description: >-
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.
maxLength: 64
minLength: 1
pattern: ^.{1,64}$
example: external-id-2468
retryDays:
type: integer
format: int32
minimum: 0
maximum: 14
example: 5
description: >-
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:
$ref: '#/components/schemas/ProcessingMode'
status:
$ref: '#/components/schemas/ChargeStatus'
transactionId:
type: string
description: Contains null until the status has reached CHARGED
maxLength: 36
pattern: ^\d{10,}$
example: '5001419121'
type:
$ref: '#/components/schemas/ChargeTypeV3'
transactionType:
$ref: '#/components/schemas/transactionType'
failureReason:
type: string
nullable: true
enum:
- user_action_required
- charge_amount_too_high
- non_technical_error
- technical_error
example: user_action_required
description: |
Identifies the reason why the charged has been marked as `FAILED`:
* `user_action_required` - The user's card can not fulfil the payment, user needs to take action in the Vipps or MobilePay app.
Examples: Card is blocked for ecommerce, insufficient funds, expired card.
* `charge_amount_too_high` - The user's max amount is too low, user needs to update their max amount in the Vipps or MobilePay app.
* `non_technical_error` - Something went wrong with charging the user.
Examples: User has deleted their Vipps MobilePay Profile.
* `technical_error` - Something went wrong in Recurring while performing the payment.
Examples: Failure in Recurring, failure in downstream services.
failureDescription:
type: string
description: Description for the failure reason
example: User action required
summary:
$ref: '#/components/schemas/ChargeSummary'
history:
$ref: '#/components/schemas/ChargeHistory'
RefundRequest:
title: Refund charge request
type: object
required:
- amount
- description
properties:
amount:
type: integer
format: int32
example: 5000
description: >-
The amount to refund on a captured/charged charge, specified in
minor units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
description:
type: string
minLength: 1
example: Forgot to apply discount, refunding 50%
description: >-
A textual description of the operation, which will be displayed in
the user's app.
CaptureRequestV3:
title: Capture charge request
type: object
required:
- amount
properties:
amount:
type: integer
format: int32
example: 5000
description: >-
The amount to capture on a reserved charge, specified in minor
units.
See: [Payment
amounts](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/#payment-amounts).
description:
type: string
minLength: 1
maxLength: 100
example: TV subscription for May
description: Deprecated. Description in CreateChargeV3 is used instead.
deprecated: true
TimePeriod:
title: Time Period request
description: >-
A period of time, defined by a unit (DAY, WEEK, ...) and a count (number
of said units)
type: object
required:
- unit
- count
properties:
unit:
type: string
example: WEEK
description: Unit of time
enum:
- YEAR
- MONTH
- WEEK
- DAY
count:
type: integer
format: int32
minimum: 1
maximum: 31
exclusiveMinimum: false
exclusiveMaximum: false
example: 2
description: >-
Number of units in the time period. Example: unit=week, count=2 to
define two weeks
TimePeriodResponse:
title: Time Period response
description: >-
A period of time, defined by a unit (DAY, WEEK, ...) and a count (number
of said units)
type: object
properties:
unit:
type: string
example: WEEK
description: Unit of time
enum:
- YEAR
- MONTH
- WEEK
- DAY
count:
type: integer
format: int32
example: 2
description: >-
Number of units in the time period. Example: unit=week, count=2 to
define two weeks
text:
type: string
description: >-
Textual representation used in Vipps MobilePay to describe the time
period
example: every 2 weeks
ForceAcceptAgreement:
title: Force accept agreement request
type: object
required:
- customerPhoneNumber
properties:
customerPhoneNumber:
type: string
example: '12345678'
ForceAcceptAgreementV3:
title: Force accept agreement request
type: object
required:
- phoneNumber
properties:
phoneNumber:
type: string
example: '4712345678'
ErrorFromAzure:
type: object
description: >-
An error from Microsoft Azure. We have limited control of these errors,
and can not give as detailed information as with the errors from our own
code.
The most important property is the HTTP status code.
required:
- responseInfo
- result
properties:
responseInfo:
type: object
required:
- responseCode
- responseMessage
properties:
responseCode:
type: integer
example: 401
responseMessage:
type: string
example: Unauthorized
result:
type: object
required:
- message
properties:
message:
type: string
description: 'When possible: A description of what went wrong.'
example: >-
(An error from Azure API Management, possibly related to
authentication)
ErrorV3:
title: Error response
description: >-
The standard error object, based on RFC 7807. See [Recurring API
problems](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-problems/)
type: object
properties:
type:
type: string
description: Path to type of error
title:
type: string
description: Short description of the error
status:
type: integer
format: int32
description: HTTP status returned with the problem
detail:
type: string
description: Details about the error
instance:
type: string
description: The path of the request
contextId:
type: string
description: An unique ID for the request
extraDetails:
type: array
items:
$ref: '#/components/schemas/ExtraDetails'
ExtraDetails:
title: Extra details
description: extra details about the error
type: object
properties:
name:
type: string
description: Name of the field related to the error
reason:
type: string
description: Details about the error
responses:
ErrorResponseV3:
description: Standard problem response.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorV3'
headers: {}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment