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: 2.6.16 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 v2 endpoints (deprecated) description: Will not be available from November 1, 2023 - name: Agreement v3 endpoints - name: Charge v2 endpoints (deprecated) description: Will not be available from November 1, 2023 - name: Charge v3 endpoints paths: /recurring/v2/agreements: get: deprecated: true tags: - Agreement v2 endpoints (deprecated) summary: List Agreements description: >- The API call allows merchant to fetch all agreements. If no query status is supplied it will default to only retrieving active agreements. There is no way to list all Agreements with all statuses, this is due to performance. Use the `createdAfter` query to paginate the response. operationId: ListAgreements 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' responses: '200': description: OK' content: application/json: schema: type: array items: $ref: '#/components/schemas/AgreementResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' post: deprecated: true tags: - Agreement v2 endpoints (deprecated) summary: Create a new Agreement, to be confirmed in Vipps description: >- The API call allows merchants to create agreements for a user to accept. Once the agreement is drafted you will receive a `vippsConfirmationUrl`. This is used to redirect the user to the Vipps landing page, or to the Vipps app if `"isApp":true` is used. If the user accepts or rejects the agreement, the user will be redirected back to whichever URL has been passed in `merchantRedirectUrl`. You **have** to implement polling on the agreement to check when the status changes to active instead of relying on the redirect back to the `merchantRedirectUrl`. We have no control over if a user is actually redirected back or not, this depends on what browser the user came from. Please note the different use cases for `initialCharge` and `campaign`. And when to use `RESERVE_CAPTURE` instead of `DIRECT_CAPTURE` as transactionType. More information about this can be found in the API documentation. operationId: DraftAgreement 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' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DraftAgreementV2' examples: Minimal: value: currency: NOK interval: MONTH intervalCount: 1 merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement customerPhoneNumber: '45678272' price: 2500 productDescription: MyNews on web productName: MyNews Digital skipLandingPage: false 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: currency: NOK interval: MONTH intervalCount: 1 merchantRedirectUrl: https://merchant.redirect.url.no merchantAgreementUrl: https://merchant.agreement.url.no customerPhoneNumber: '45678272' price: 2500 productDescription: MyNews on web productName: MyNews Digital skipLandingPage: false 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: currency: NOK interval: MONTH intervalCount: 1 isApp: false merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement customerPhoneNumber: '45678272' price: 2500 productDescription: MyNews on web productName: MyNews Digital skipLandingPage: false campaign: campaignPrice: 100 end: 2022/02/28T00:00:00Z With Price Campaign and Initial Charge: 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: currency: NOK interval: MONTH intervalCount: 1 isApp: false merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement customerPhoneNumber: '45678272' price: 2500 productDescription: MyNews on web productName: MyNews Digital skipLandingPage: false campaign: campaignPrice: 100 end: 2022/02/28T00:00:00Z initialCharge: amount: 100 currency: NOK description: Initial 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: currency: NOK interval: MONTH intervalCount: 1 isApp: false merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement customerPhoneNumber: '45678272' productDescription: Power on web productName: MyNews Digital skipLandingPage: false variableAmount: suggestedMaxAmount: 3000 With Profile Flow: description: >- User consents to sharing data that can be retrieved after they accept the agreement. value: currency: NOK interval: MONTH intervalCount: 1 isApp: false merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement customerPhoneNumber: '45678272' price: 2500 productDescription: Power on web productName: MyNews Digital scope: address name email birthDate phoneNumber responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/DraftAgreementResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v2/agreements/{agreementId}: get: deprecated: true tags: - Agreement v2 endpoints (deprecated) 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: FetchAgreement 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/AgreementResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' put: deprecated: true tags: - Agreement v2 endpoints (deprecated) 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: UpdateAgreementPut 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' requestBody: description: agreement required: true content: application/json: schema: $ref: '#/components/schemas/PatchAgreementV2' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgreementReference' default: $ref: '#/components/responses/ErrorResponseV2' patch: deprecated: true tags: - Agreement v2 endpoints (deprecated) 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: UpdateAgreementPatch 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' requestBody: description: agreement required: true content: application/json: schema: $ref: '#/components/schemas/PatchAgreementV2' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgreementReference' default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v2/agreements/{agreementId}/accept: patch: deprecated: true tags: - Agreement v2 endpoints (deprecated) 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: acceptUsingPATCH 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' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ForceAcceptAgreement' responses: '200': description: OK content: application/json: schema: type: object default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v3/agreements: get: tags: - Agreement v3 endpoints summary: List Agreements description: >- The API call allows merchant to fetch all agreements. If no query status is supplied it will default to only retrieving active agreements. There is no way to list all Agreements with all statuses, this is due to performance. Use the `createdAfter` query to paginate the response. operationId: ListAgreementsV3 parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Continuation-Token' - $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' responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/AgreementResponseV3' default: $ref: '#/components/responses/ErrorResponseV3' deprecated: false post: tags: - Agreement v3 endpoints summary: Create a new Agreement, to be confirmed in Vipps description: >- The API call allows merchants to create agreements for a user to accept. Once the agreement is drafted you will receive a `vippsConfirmationUrl`. This is used to redirect the user to the Vipps landing page, or to the Vipps app if `"isApp":true` is used. If the user accepts or rejects the agreement, the user will be redirected back to whichever URL has been passed in `merchantRedirectUrl`. You **have** to implement polling on the agreement to check when the status changes to active instead of relying on the redirect back to the `merchantRedirectUrl`. We have no control over if a user is actually redirected back or not, this depends on what browser the user came from. Please note the different use cases for `initialCharge` and `campaign`. And when to use `RESERVE_CAPTURE` instead of `DIRECT_CAPTURE` as transactionType. More information about this can be found in the API documentation. 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: value: pricing: type: LEGACY amount: 2500 currency: NOK interval: unit: MONTH count: 1 merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement phoneNumber: '45678272' 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: '45678272' 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: '45678272' 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: '45678272' 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: '45678272' 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 Full Flex Campaign: value: pricing: type: LEGACY amount: 2500 currency: NOK interval: unit: MONTH count: 1 merchantRedirectUrl: https://example.com/redirect merchantAgreementUrl: https://example.com/agreement phoneNumber: '45678272' productName: MyNews Digital campaign: type: FULL_FLEX_CAMPAIGN price: 100 end: 2022/03/13T00:00:00Z interval: unit: WEEK count: 2 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: '45678272' 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: '45678272' productName: MyNews Digital scope: address name email birthDate phoneNumber responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/DraftAgreementResponseV3' default: $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' default: $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 default: $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 default: $ref: '#/components/responses/ErrorResponseV3' deprecated: false /recurring/v2/agreements/{agreementId}/charges: get: deprecated: true tags: - Charge v2 endpoints (deprecated) summary: List Charges description: >- Fetches all charges for a single agreement, including the optional initial charge. Supports filtering on status using query parameter. operationId: ListCharges 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/ChargeStatusQuery' responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/ChargeResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' post: deprecated: true tags: - Charge v2 endpoints (deprecated) 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: CreateCharge 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/CreateChargeV2' responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/ChargeReference' default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v2/agreements/{agreementId}/charges/{chargeId}: get: deprecated: true tags: - Charge v2 endpoints (deprecated) summary: Fetch a Charge description: Fetch a single charge for a user. operationId: FetchCharge 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/ChargeResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' delete: deprecated: true tags: - Charge v2 endpoints (deprecated) 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 by Vipps. operationId: CancelCharge 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/ChargeResponseV2' default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v2/agreements/{agreementId}/charges/{chargeId}/capture: post: deprecated: true tags: - Charge v2 endpoints (deprecated) summary: Capture a reserved charge description: |- Captures a reserved charge. Only charges with transactionType `RESERVE_CAPTURE` can be captured. operationId: CaptureCharge 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: '200': description: Success content: application/json: schema: type: object default: $ref: '#/components/responses/ErrorResponseV2' /recurring/v2/agreements/{agreementId}/charges/{chargeId}/refund: post: deprecated: true tags: - Charge v2 endpoints (deprecated) summary: Refund a charge description: >- Refunds a charge, can also do a partial refund (refunding a smaller part of the payment). operationId: RefundCharge 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: '200': description: Success content: application/json: schema: type: object default: $ref: '#/components/responses/ErrorResponseV2' /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' default: $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' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ChargeReference' default: $ref: '#/components/responses/ErrorResponseV3' deprecated: false /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' default: $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 by Vipps. 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 default: $ref: '#/components/responses/ErrorResponseV3' deprecated: false /recurring/v3/charges/{chargeId}: get: tags: - Charge v3 endpoints summary: Fetch a charge by id description: >- Fetch a single charge just by `chargeId`, when the `agreementId` is unknown. Useful for investigating claims from customers, but not intended for automation. This is *not* a replacement for the normal endpoint for fetching charges: `GET:/agreements/{agreementId}/charges/{chargeId}`. 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' default: $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 default: $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: '202': description: >- Accepted. Request accepted, the action will likely succeed but has not yet been enacted. '204': description: No content default: $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 API product is available on portal.vipps.no, under the 'Utvikler' tab. 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 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. 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 that this payment is made for. This is a required parameter if you are a Vipps Recurring partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves. schema: type: string example: 123456 AgreementStatusQuery: in: query name: status required: false description: Filter by status of the agreement. schema: $ref: '#/components/schemas/AgreementStatus' CreatedAfterQuery: in: query name: createdAfter required: false description: Filter by createdAfter timestamp for paginating. schema: type: integer format: int32 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' 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/common-topics/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/common-topics/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/common-topics/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/common-topics/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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. cancelled: type: integer format: int32 example: 19900 description: >- The total amount which has been cancelled. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 description: |- Date and time of the event, on the format `2022-09-05T14:25:55Z`. 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 CurrencyV3: type: string description: 'ISO-4217: https://www.iso.org/iso-4217-currency-codes.html' enum: - NOK minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ example: NOK transactionType: type: string description: Type of transaction, either direct capture or reserve capture enum: - DIRECT_CAPTURE - RESERVE_CAPTURE example: DIRECT_CAPTURE ChargeType: type: string default: RECURRING enum: - INITIAL - RECURRING example: RECURRING Interval: type: string description: Interval for subscription default: MONTH pattern: ^(YEAR|MONTH|WEEK|DAY)$ enum: - YEAR - MONTH - WEEK - DAY example: MONTH DraftAgreementV2: title: DraftAgreement type: object required: - currency - interval - intervalCount - merchantAgreementUrl - merchantRedirectUrl - price - productName properties: variableAmount: $ref: '#/components/schemas/variableAmount' campaign: $ref: '#/components/schemas/campaignV2' currency: $ref: '#/components/schemas/Currency' customerPhoneNumber: type: string description: >- Customers phone number (if available). Used to simplify the following Vipps interaction. MSISDN: https://en.wikipedia.org/wiki/MSISDN maxLength: 15 example: '4791234567' initialCharge: $ref: '#/components/schemas/InitialChargeV2' interval: $ref: '#/components/schemas/Interval' intervalCount: type: integer format: int32 description: |- Number of intervals between charges. Example: interval=week, intervalCount=2 to be able to charge every two weeks. Charges should occur at least once a year. minimum: 1 maximum: 31 example: 2 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 landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to Vipps will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/common-topics/isApp example: false default: false merchantAgreementUrl: type: string maxLength: 1024 description: >- URL where Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer management tools, not just information about how to contact customer service, etc. We recommend letting users [log in with Vipps](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 HTTP or HTTPS scheme is allowed. 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 mobile application. HTTPS and deeplinks are allowed (example: myApp://home) example: https://example.com/landing price: type: integer format: int32 example: 7900 description: >- The price of the agreement. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. productName: type: string description: Product name (short) maxLength: 45 example: Premier League subscription productDescription: type: string description: Product description (longer) maxLength: 100 example: Access to all games of English top football scope: type: string description: >- Space separated list of the user profile-data scope to require for the agreement. 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 by Vipps for eligible sales units: The sales units must be whitelisted by Vipps. If the sales unit is not whitelisted, the request will fail and an error message will be returned (statusCode=403). See: https://developer.vippsmobilepay.com/docs/common-topics/landing-page default: false example: false DraftAgreementV3: title: DraftAgreement type: object required: - pricing - interval - merchantAgreementUrl - merchantRedirectUrl - productName properties: campaign: $ref: '#/components/schemas/campaignV3' pricing: $ref: '#/components/schemas/pricingRequest' phoneNumber: type: string description: >- Customers phone number (if available). Used to simplify the following Vipps interaction. MSISDN: https://en.wikipedia.org/wiki/MSISDN maxLength: 15 example: '4791234567' 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 landing page or deeplink URL to connect vipps App. When isApp is set to true, URLs passed to Vipps will not be validated as regular URLs. See: https://developer.vippsmobilepay.com/docs/common-topics/isApp example: false default: false merchantAgreementUrl: type: string maxLength: 1024 description: >- URL where Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users [log in with Vipps](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. 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 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 user profile-data scope to require for the agreement. 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 by Vipps for eligible sales units: The sales units must be whitelisted by Vipps. If the sales unit is not whitelisted, the request will fail and an error message will be returned (statusCode=403). See: https://developer.vippsmobilepay.com/docs/common-topics/landing-page default: false example: false 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: type: string example: 'NO' pattern: ^[A-Z]{2}$ enum: - 'NO' description: >- An optional country code for the agreement according to ISO 3166-2 (two capital letters) DraftAgreementResponseV2: title: DraftAgreementResponse type: object required: - agreementId - agreementResource - vippsConfirmationUrl - chargeId properties: agreementResource: type: string description: >- Reference 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 Vipps. example: https://api.vipps.no/v2/agreement/agr_5kSeqz 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 Vipps. example: agr_5kSeqz vippsConfirmationUrl: type: string description: |- The `vippsConfirmationUrl` should be used to redirect the user to the Vipps landing page in a desktop flow (with `https://`), or to the Vipps 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 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}$ 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 Vipps. 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 landing page in a desktop flow (with `https://`), or to the Vipps 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 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}$ AgreementResponseV2: title: Agreement response type: object required: - id - interval - intervalCount - price - productName - productDescription properties: campaign: $ref: '#/components/schemas/campaignV2' currency: $ref: '#/components/schemas/Currency' id: type: string example: agr_DdLnJAF maxLength: 36 description: Uniquely identifies this agreement interval: $ref: '#/components/schemas/Interval' intervalCount: type: integer format: int32 description: >- Number of intervals between charges. Example: interval=WEEK, intervalCount=2 to be able to charge every two weeks. Charges should occur at least once a year. minimum: 1 maximum: 31 example: 2 price: type: integer format: int32 example: 49900 description: >- The price of the agreement. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. minimum: 0 productName: type: string description: Product name (short) maxLength: 45 example: Premier League subscription productDescription: type: string description: Product description (longer) maxLength: 100 example: Access to all games of English top football start: type: string format: date-time description: Date when agreement was started in ISO 8601 format. example: '2019-01-01T00:00:00Z' nullable: true stop: type: string format: date-time description: Date when agreement was stopped in ISO 8601 format. nullable: true example: null status: $ref: '#/components/schemas/AgreementStatus' merchantAgreementUrl: type: string description: >- URL where Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS. example: https://example.com/vipps-subscriptions/1234/ 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#tag/Vipps-Userinfo-API/operation/getUserinfo). This will be null if profile data was not requested. nullable: true variableAmount: $ref: '#/components/schemas/variableAmountResponse' AgreementResponseV3: title: Agreement response type: object required: - id - interval - pricing - productName - uuid - countryCode - created - merchantAgreementUrl - merchantRedirectUrl properties: campaign: $ref: '#/components/schemas/campaignResponseV3' pricing: $ref: '#/components/schemas/pricingResponse' 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. example: '2019-01-01T00:00:00Z' start: type: string format: date-time description: Date when agreement was started in ISO 8601 format. example: '2019-01-01T00:00:00Z' nullable: true stop: type: string format: date-time description: Date when agreement was stopped in ISO 8601 format. nullable: true example: null status: $ref: '#/components/schemas/AgreementStatus' merchantAgreementUrl: type: string description: >- URL where Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS. 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 mobile application. 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#tag/Vipps-Userinfo-API/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: type: string example: 'NO' pattern: ^[A-Z]{2}$ enum: - 'NO' description: >- An optional country code for the agreement according to ISO 3166-2 (two capital letters) 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 landing page in a desktop flow (with `https://`), or to the Vipps app in a mobile flow (with `vipps://`), where the user can then approve the agreement. example: https://api.vipps.no/v2/register/U6JUjQXq8HQmmV PatchAgreementV2: title: PatchAgreement type: object properties: suggestedMaxAmount: type: integer format: int32 example: 3000 minimum: 100 maximum: 2000000 description: >- The suggested max amount that the customer should choose. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. campaign: $ref: '#/components/schemas/campaignV2' price: type: integer format: int32 example: 7900 minimum: 0 description: >- The price of the agreement. Price is specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. productName: type: string description: Product name (short) maxLength: 45 example: Premier League subscription productDescription: type: string description: Product description (longer) maxLength: 100 example: Access to all games of English top football merchantAgreementUrl: type: string maxLength: 1024 description: >- URL where Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS. example: https://example.com/vipps-subscriptions/1234/ status: type: string example: STOPPED description: Status of the agreement. enum: - STOPPED 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 Vipps can send the customer to view/manage their subscription. Typically a "My page" where the user can change, pause, cancel, etc. The page must offer actual management, not just information about how to contact customer service, etc. We recommend letting users log in with Vipps, not with username and password: https://developer.vippsmobilepay.com/docs/APIs/login-api We do not have any specific requirements for the security of the page other than requiring HTTPS. 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' 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 Vipps. variableAmount: title: Variable Amount request type: object required: - suggestedMaxAmount properties: suggestedMaxAmount: type: integer format: int32 example: 3000 minimum: 100 maximum: 2000000 description: >- The suggested max amount that the customer should choose. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. variableAmountResponse: title: Variable Amount response type: object properties: suggestedMaxAmount: type: integer format: int32 example: 3000 description: >- The suggested max amount that the customer should choose. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. maxAmount: type: integer format: int32 example: 3000 description: >- The max amount chosen by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. campaignV2: title: Campaign request type: object nullable: true required: - campaignPrice - end properties: campaignPrice: 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. end: type: string format: date-time example: '2022-12-31T00:00:00Z' description: >- The date and time the campaign ends. This is a required field for `EVENT_CAMPAIGN`, and is illegal for other types. But: If you add this type of info, you also need to add that interval and end is used by `FULL_FLEX_CAMPAIGN` and that period is used by `PERIOD_CAMPAIGN`, etc. Must be UTC. campaignResponseV2: title: Campaign response type: object properties: campaignPrice: 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. start: type: string format: date-time example: '2022-12-31T00:00:00Z' description: The date and time the campaign starts. Must be UTC. end: type: string format: date-time example: '2022-12-31T00:00:00Z' description: |- The date and time the campaign ends. This is a required field when using `EVENT_CAMPAIGN`. Must be UTC. campaignV3: oneOf: - $ref: '#/components/schemas/priceCampaignV3' - $ref: '#/components/schemas/periodCampaignV3' - $ref: '#/components/schemas/eventCampaignV3' - $ref: '#/components/schemas/fullFlexCampaignV3' discriminator: propertyName: type 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 - PERIOD_CAMPAIGN - EVENT_CAMPAIGN - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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: - PRICE_CAMPAIGN - PERIOD_CAMPAIGN - EVENT_CAMPAIGN - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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: - PRICE_CAMPAIGN - PERIOD_CAMPAIGN - EVENT_CAMPAIGN - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 fullFlexCampaignV3: title: Full flex campaign type: object nullable: true required: - type - price - interval - end properties: type: type: string description: The type of campaign. This decides which properties are required enum: - PRICE_CAMPAIGN - PERIOD_CAMPAIGN - EVENT_CAMPAIGN - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. interval: $ref: '#/components/schemas/TimePeriod' end: type: string example: '2019-06-01T00:00:00Z' description: |- The date and time the campaign ends. Needs to be UTC. campaignResponseV3: oneOf: - $ref: '#/components/schemas/priceCampaignResponseV3' - $ref: '#/components/schemas/periodCampaignResponseV3' - $ref: '#/components/schemas/eventCampaignResponseV3' - $ref: '#/components/schemas/fullFlexCampaignResponseV3' - $ref: '#/components/schemas/legacyCampaignResponseV3' discriminator: propertyName: type 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 - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 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 - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 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 - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 app to explain the campaign to the user fullFlexCampaignResponseV3: title: Full Flex Campaign type: object required: - type - price - end - interval properties: type: type: string description: The type of campaign. This decides which properties are required enum: - PRICE_CAMPAIGN - PERIOD_CAMPAIGN - EVENT_CAMPAIGN - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. end: type: string example: '2019-06-01T00:00:00Z' description: |- The date and time the campaign ends. Needs to be UTC. interval: $ref: '#/components/schemas/TimePeriod' explanation: type: string example: Ordinary price 399 kr starts 6/12/2022 description: >- The text displayed in the Vipps 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 - FULL_FLEX_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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 app to explain the campaign to the user pricingRequest: title: DraftAgreementPricingRequest type: object required: - currency properties: type: type: string description: The type of pricing. This decides which properties are required. enum: - LEGACY - VARIABLE default: LEGACY currency: $ref: '#/components/schemas/CurrencyV3' amount: type: integer format: int32 minimum: 100 example: 1500 description: >- The price of the agreement, required if type is LEGACY or not present. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. suggestedMaxAmount: type: integer format: int32 minimum: 100 maximum: 2000000 example: 3000 description: >- The suggested max amount that the customer should choose, required if type is VARIABLE. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. pricingResponse: title: AgreementPricingResponse type: object properties: type: type: string description: The type of pricing. This decides which properties are present. enum: - LEGACY - VARIABLE currency: $ref: '#/components/schemas/Currency' amount: type: integer format: int32 example: 1500 description: >- The price of the agreement, present if type is LEGACY. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. suggestedMaxAmount: type: integer format: int32 example: 30000 description: >- The suggested max amount that the customer should choose, present if type is VARIABLE. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. maxAmount: type: integer format: int32 example: 30000 description: >- The max amount chosen by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. PricingUpdateRequest: title: UpdateAgreementPricingRequest type: object properties: amount: type: integer format: int32 minimum: 100 example: 1500 description: >- The price of the agreement, can only be updated if agreement type is LEGACY Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. suggestedMaxAmount: type: integer format: int32 minimum: 100 maximum: 2000000 example: 3000 description: >- The suggested max amount that the customer should choose, can only be updated if agreement type is VARIABLE. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. InitialChargeV2: 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 - currency - 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. currency: $ref: '#/components/schemas/Currency' description: type: string 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 orderId for the payment, auto generated otherwise 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. description: type: string 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 orderId for the payment, auto generated otherwise 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 CreateChargeV2: title: CreateCharge type: object required: - amount - currency - description - due - retryDays properties: amount: type: integer format: int32 minimum: 100 example: 19900 description: >- Amount to be paid by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. currency: $ref: '#/components/schemas/Currency' description: type: string minimum: 1 maximum: 45 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 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. orderId: type: string maximum: 50 pattern: ^[a-zA-Z\d-]+ example: acme-shop-123-order123abc description: An optional orderId for the payment, auto generated otherwise. CreateChargeV3: title: CreateCharge type: object required: - amount - description - due - retryDays - transactionType properties: amount: type: integer format: int32 minimum: 100 example: 19900 description: >- Amount to be paid by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. transactionType: $ref: '#/components/schemas/transactionType' description: type: string minimum: 1 maximum: 45 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. If the charge is `DIRECT_CAPTURE`, the charge is processed and charged on due date. If the charge is `RESERVE_CAPTURE`, the charge is `RESERVED` on due date. Must be in the format `YYYY-MM-DD` and ISO 8601. 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. orderId: type: string maximum: 50 pattern: ^[a-zA-Z\d-]+ example: acme-shop-123-order123abc description: An optional orderId for the payment, auto generated otherwise 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 ChargeReference: type: object title: Charge reference properties: chargeId: type: string example: chg_WCVbcAbRCmu2zk description: Unique identifier for this charge, up to 15 characters. ChargeResponseV2: title: ChargeResponse type: object required: - transactionId - description - type - amount - amountRefunded - due - id - status properties: amount: type: integer format: int32 example: 19900 description: >- Amount to be paid by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. amountRefunded: 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. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. 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 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/ChargeType' failureReason: type: string 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. The user needs to take action in Vipps. Examples: Card is blocked for ecommerce, insufficient funds, expired card. * `charge_amount_too_high` - The user's max amount is too low. The user needs to update their max amount in Vipps. * `non_technical_error` - Something went wrong with charging the user. Examples: User has deleted their Vipps 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 ChargeResponseV3: title: ChargeResponse type: object required: - transactionId - description - type - transactionType - amount - summary - history - due - id - status - currency - agreementId - externalId - externalAgreementId - retryDays properties: amount: type: integer format: int32 example: 19900 description: >- Amount to be paid by the customer. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. currency: $ref: '#/components/schemas/Currency' 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. 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/ChargeType' transactionType: $ref: '#/components/schemas/transactionType' failureReason: type: string 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 Vipps. 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 Vipps. * `non_technical_error` - Something went wrong with charging the user. Examples: User has deleted their Vipps 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 minimum: 100 example: 5000 description: >- The amount to refund on a captured/charged charge. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. description: type: string minimum: 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 - description properties: amount: type: integer format: int32 minimum: 100 example: 5000 description: >- The amount to capture on a reserved charge. Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. description: type: string minimum: 1 example: Not all items were in stock. Partial capture. description: >- A textual description of the operation, which will be displayed in the user's app. 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 for time period 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 for time period 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 to describe the time period example: every 2 weeks ForceAcceptAgreement: title: Force accept agreement request type: object required: - customerPhoneNumber properties: customerPhoneNumber: type: string example: '91234567' ForceAcceptAgreementV3: title: Force accept agreement request type: object required: - phoneNumber properties: phoneNumber: type: string example: '91234567' ErrorFromAzure: type: object description: >- An error from Microsoft Azure. Vipps has 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) ErrorV2: title: Error response description: |- An error from Vipps. The most important property is the HTTP status code. The response body contains more details of the error. type: object properties: field: type: string description: Field that caused the error example: agreement.status message: type: string description: The error message example: Cannot create a charge for an agreement which is not active. code: type: string description: The code for the specific error example: recurring.core.charges.create.invalid_agreement contextId: type: string description: A unique id for this error, useful for searching in logs example: f70b8bf7-c843-4bea-95d9-94725b19895f ErrorArray: type: array items: $ref: '#/components/schemas/ErrorV2' ErrorV3: title: Error response description: Error response using the Problem JSON format type: object properties: type: type: string description: Path to type of error example: >- https://developer.vippsmobilepay.com/docs/APIs/recurring-api/vipps-recurring-api-problems#validation-error title: type: string description: Short description of the error example: Bad Request status: type: integer format: int32 description: HTTP status returned with the problem example: 400 detail: type: string description: Details about the error example: Input validation failed instance: type: string description: The path of the request example: /v3/agreements contextId: type: string description: An unique ID for the request example: f70b8bf7-c843-4bea-95d9-94725b19895f extraDetails: type: array items: type: object description: Additional properties properties: field: type: string description: Field to provide additional details on example: productName text: type: string description: Details for the error of a specific field example: must not be empty responses: ErrorResponseV2: description: |- Possible error responses. Errors can be from both Vipps' own code (where we have full control) and from Microsoft Azure (where we rely on standard functionality). content: application/json;charset=UTF-8: schema: oneOf: - $ref: '#/components/schemas/ErrorArray' - $ref: '#/components/schemas/ErrorFromAzure' ErrorResponseV3: description: |- Possible error responses. Errors can be from both Vipps' own code (where we have full control) and from Microsoft Azure (where we rely on standard functionality). content: application/json;charset=UTF-8: schema: oneOf: - $ref: '#/components/schemas/ErrorV3' - $ref: '#/components/schemas/ErrorFromAzure'