Skip to main content

How charge creation works for PSPs

View as Markdown (opens in a new tab)
Install AI tools

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

For troubleshooting, see the full instructions.

A step-by-step walkthrough of charging an active agreement, from the batch request to the reported result.

Charge creation is PSP-initiated — there is no user interaction. The PSP submits a batch of charges against active agreements, obtains the card data for each charge, processes the payments, and reports each outcome back to update the charge status. How the card data is delivered depends on the charge type: it is returned at creation for UNSCHEDULED charges, but fetched on the due date via Get payment info for scheduled RECURRING charges.

Details​

1. The PSP submits a batch of charges​

The PSP submits a batch of charges with POST:/recurring/v4/agreements/charges. The request must include the Merchant-Serial-Number header for the merchant the PSP is creating charges for. Each charge is validated and created independently.

2. Vipps MobilePay returns the batch result​

Vipps MobilePay returns a response split into successfulCharges, failedCharges, and retryableCharges. For each successful UNSCHEDULED charge, the response includes the card data needed for downstream processing: a network token if available, otherwise an encrypted PAN (only when publicEncryptionKeyId is set on the agreement). RECURRING charges are created DUE for a future date and do not include card data in this response. Retry items in retryableCharges with the same agreementId and chargeId.

3. The PSP fetches the card data for recurring charges​

For a RECURRING charge, on the due date the PSP fetches the current card data with GET:/recurring/v4/agreements/{agreementId}/charges/{chargeId}/payment-info. UNSCHEDULED charges skip this step — they already have card data from step 2.

4. The PSP processes the payment​

The PSP processes each payment using its own acquiring infrastructure.

5. The PSP reports the charge result​

For each charge, the PSP reports the outcome with POST:/recurring/v4/agreements/{agreementId}/charges/{chargeId}/result: SUCCESS for a successfully processed payment, or FAILED with an error object for a failed payment. For RECURRING charges, Get payment info must have been called first. Without reporting the result, the charge stays unresolved and the user sees a due or overdue charge they cannot act on.

Sequence diagrams​

A single batch can contain both unscheduled and recurring charges; the per-charge flow differs by type, shown separately below.

PSP unscheduled charge flow (v4 batch)

100%
  1. PSP submits a batch of unscheduled charges with Vipps MobilePay (POST /recurring/v4/agreements/charges).
  2. Vipps MobilePay returns the response split into successfulCharges (each including the card data needed for downstream processing), failedCharges (with non-retryable error messages), and retryableCharges (with transient errors that can be retried with the same agreementId and chargeId).
  3. For each successful charge: PSP processes the payment downstream, then reports the outcome to Vipps MobilePay using the result endpoint, which returns 202 Accepted.

PSP recurring charge flow (v4 batch)

100%
  1. PSP submits a batch of recurring charges with Vipps MobilePay (POST /recurring/v4/agreements/charges), each with a future due date.
  2. Vipps MobilePay returns the response split into successfulCharges (created DUE, without card data), failedCharges (with non-retryable error messages), and retryableCharges (with transient errors that can be retried with the same agreementId and chargeId).
  3. On the due date, for each successful charge the PSP fetches the current card data with GET .../payment-info.
  4. The PSP processes the payment downstream, then reports the outcome to Vipps MobilePay using the result endpoint, which returns 202 Accepted.

More information​

For the full flow and request details, see the Recurring PSP API guide.

Last updated on