Skip to main content
Coming soon

The ePayment PSP API is not yet available. This documentation describes the upcoming functionality.

ePayment PSP API guide

PSPs can process card payments through their own infrastructure using CARD_PASSTHROUGH as the payment method type. When the user selects a card in the Vipps MobilePay app, the card token is sent to your callback URL. You process the payment and respond with the result.

This page covers the PSP-specific additions.

tip

The ePayment API covers the full breadth of the underlying platform — including detailed flow diagrams, user journey walkthroughs, and advanced features that apply to PSP integrations as well.

Flow​

With CARD_PASSTHROUGH, the payment creation flow is:

  1. PSP creates a payment with paymentMethod.type: CARD_PASSTHROUGH and a cardPassthrough object specifying your callback URL (cardCallbackUrl).
  2. The user is redirected to the Vipps MobilePay app and selects a card.
  3. Vipps MobilePay sends the card token to cardCallbackUrl synchronously.
  4. PSP processes the payment using own payment processing systems and responds within 20 seconds.
  5. The user is redirected to your returnUrl.
  6. PSP updates the payment status in Vipps MobilePay.

PSP merchant payment flow

Endpoints​

PSPs can use all ePayment API endpoints with the Psp-Id header added to every request. The only endpoint requiring PSP-specific configuration is POST:/epayment/v1/payments.

The following table shows how ePayment endpoints are used in a PSP CARD_PASSTHROUGH integration.

ePayment endpointsPSP usage and notes
Create payment:
POST:/epayment/v1/payments		Create CARD_PASSTHROUGH payment with Psp-Id and cardPassthrough callback fields. See Create payment.
Update the payment status:
POST:/epayment/v1/payments/{reference}/capture
POST:/epayment/v1/payments/{reference}/refund
POST:/epayment/v1/payments/{reference}/cancel		Communicate capture, refund, and cancel status to Vipps MobilePay. Payment processing happens in PSP/acquirer systems. See Update the payment status.
Check the payment status:
GET:/epayment/v1/payments/{reference}
GET:/epayment/v1/payments/{reference}/events		Optional: compare current state/amounts with PSP records and decide if updates are needed. See Check the payment status.

Create payment​

The payment flow is user-initiated. The user selects a card in the Vipps MobilePay app, and Vipps MobilePay calls your cardCallbackUrl synchronously with the card token. You process the payment and respond with the result, then update us with the outcome.

Send a POST:/epayment/v1/payments request with the required parameters. Set paymentMethod.type to CARD_PASSTHROUGH and include the cardPassthrough object.

Example request (PSP-specific fields are highlighted):

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Psp-Id: YOUR-PSP-ID" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \ 
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 6000
  },
  "customer": {
    "phoneNumber": "4712345678"
  },
  "paymentMethod": {
    "type": "CARD_PASSTHROUGH"
  },
  "cardPassthrough": {
    "pspReference": "payment-ref-123456",
    "cardCallbackUrl": "https://example.com/psp-callback",
    "cardCallbackAuthHeader": "Bearer your-secure-token",
    "allowedCardTypes": ["VISA_DEBIT", "VISA_CREDIT", "DANKORT", "MC_CREDIT", "MC_DEBIT"],
    "publicEncryptionKeyId": "3f1c2e90-7a4b-4c9d-8f21-6b3e2d7a91c4"
  },
  "reference": "acme-shop-123-order123abc",
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "https://example.com/redirect?orderId=1512202",
  "paymentDescription": "Purchase of socks"
}'

When the user confirms the payment in the Vipps MobilePay app and selects their card, Vipps MobilePay sends a card token to your cardCallbackUrl. See Card callback for the request format, HMAC authentication, and expected response.

Once you've processed the payment, update payment status so that the Vipps MobilePay app will show the user the correct status.

Parameters​

Required header parameters

  • Authorization - Bearer-Authorization. The access token is a base64-encoded string that is required for all API calls.
  • Idempotency-Key - Idempotency key for the request, ensures idempotent actions. See Idempotency
  • Ocp-Apim-Subscription-Key - The subscription key for a sales unit. See API keys.
  • Merchant-Serial-Number - The Merchant Serial Number is a unique identifier that is defined when a sales unit is created. See How to find the Merchant Serial Number
  • Psp-Id - Only used by Payment Service Providers. If you are a PSP, see PSP ePayment integration.

There are several optional HTTP headers that are helpful for debugging (e.g., Vipps-System-Name).

Required body parameters

  • paymentMethod.type - Must be set to CARD_PASSTHROUGH.
  • cardPassthrough - Supply values as described in cardPassthrough.
  • amount - Amount object, containing a value and a currency. The minimum amounts allowed are: NOK 100 øre, DKK 1 øre, EUR 1 cent. The allowed currencies are these string values: "NOK", "DKK", "EUR", "SEK", "USD", "GBP". PSPs are not limited to using the currency registered for the sales unit.
  • reference - The reference is the unique identifier for the payment, specified when initiating the payment. The reference must be unique for the sales unit (MSN), but is not globally unique, so several MSNs may use the same reference. See the orderId / reference recommendations.
  • userFlow - The normal flow is WEB_REDIRECT. See ePayment API: userFlow for more details.
  • customer - Required for userFlow of PUSH_MESSAGE. The customer phone number or login token.
  • returnUrl - Required for userFlow of WEB_REDIRECT. The URL the user is returned to after the payment session. The URL must use the https:// scheme or a custom URL scheme.
cardPassthrough​

The cardPassthrough object is required when creating a CARD_PASSTHROUGH payment.

FieldRequiredDescription
pspReferenceYesYour unique reference for this payment.
cardCallbackUrlYesURL where we send the user's card data. See Card callback for the expected request and response format.
cardCallbackAuthHeaderNoAuthorization header value we include when calling your cardCallbackUrl.
allowedCardTypesYesCard types the user can select. Values: VISA_DEBIT, VISA_CREDIT, MC_CREDIT, MC_DEBIT, DANKORT.
preferVisaPartOfVisaDankortNoWhen true, prefer the Visa part of a Visa/Dankort co-branded card. Default: false.
publicEncryptionKeyIdNoGUID of your public key registered with us. When provided, we encrypt the PAN in the card callback. If not provided, only tokens are returned.

Update payment status​

Use these ePayment endpoints to keep us aligned with the payment state in your PSP/acquirer systems — both immediately after processing and later for captures and refunds. Include your PSP identifier in the Psp-Id header.

Check the payment status​

For reconciliation, you can optionally use:

Card callback​

The card callback applies to the payment creation flow. When the user confirms the payment in the Vipps MobilePay app and selects their card, we send a POST request to your cardCallbackUrl. You must respond within 20 seconds.

Usually the callback will include a card token and a cryptogram. It will include an encrypted PAN if you provided your publicEncryptionKeyId in the initial request.

Key behaviors:

  • The callback is synchronous — we expect a response with the payment authorization result.
  • If your response indicates a retryable error, the user can retry with the same or a different card.
  • HTTP 500 errors and timeouts are treated as non-retryable.
    • Payments can be updated later to reflect whether the payment actually became reserved.
    • We will show the user an error message: "check the payment status at the merchant you came from".

Callback request​

We send a POST request to your cardCallbackUrl with the following properties:

  • pspReference: Your unique reference for this payment, as provided in the create payment request.
  • authorizationAttemptId: Unique identifier for this authorization attempt.
  • merchantSerialNumber: The merchant serial number for the payment.
  • maskedCardNumber: The masked card number (e.g., 47969485XXXX1234).
  • cardType: The card type (e.g., VISA-DEBIT).
  • cardIssuedInCountryCode: The ISO 3166-1 alpha-2 country code where the card was issued.
  • paymentInstrument: The type of payment instrument. TOKEN indicates a network token is provided.
  • networkToken: Object containing the network token details (when paymentInstrument is TOKEN):
    • number: The token number.
    • cryptogram: The cryptogram for the transaction.
    • expiryMonth: Token expiry month.
    • expiryYear: Token expiry year.
    • tokenType: Token network type (e.g., VISA).
    • eci: Electronic Commerce Indicator.
    • paymentAccountReference: Stable reference across token renewals.
  • encryptedPan: Encrypted PAN, when provided instead of a network token.
  • softDeclineCompletedRedirectUrl: URL to redirect to after a soft decline is resolved.

For example:

POST /psp-makepayment HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "pspReference": "7686f7788898767977",
  "authorizationAttemptId": "3030303thisisaguid",
  "merchantSerialNumber": "123456",
  "softDeclineCompletedRedirectUrl": "https://vipps.no/mobileintercept?transactionId=123456789&responsecode=OK",
  "maskedCardNumber": "47969485XXXX1234",
  "cardType": "VISA-DEBIT",
  "cardIssuedInCountryCode": "DK",
  "paymentInstrument": "TOKEN",
  "networkToken": {
    "number": "5000000000000000001",
    "cryptogram": "aFgdgjdkfgjdFDF=",
    "expiryMonth": "03",
    "expiryYear": "2030",
    "tokenType": "VISA",
    "eci": "7",
    "paymentAccountReference": "5001BO8B9NXVVIXCT0HAJU98I512Z"
  },
  "encryptedPan": "xyzxyz"
}

HMAC authentication​

To verify that the callback originates from us and has not been tampered with, we sign each callback using HMAC with a shared secret.

Upon receiving the callback, the PSP must:

  1. Compute the HMAC of the received payload using the shared secret.
  2. Compare the computed value with the signature included in the request.
  3. Reject the callback if the values do not match.

This ensures message integrity and authenticity. HMAC authentication does not encrypt the payload.

Callback response​

Respond with HTTP 200 OK and a JSON body with the following properties:

  • status (required): The payment verification result. One of:
    • RESERVE — Payment verification succeeded.
    • FAIL — Payment verification failed. Provide the error reason and error codes, so the user receives a meaningful error message.
    • SOFT_DECLINE — Soft decline. Include softDeclineRedirectUrl.
  • networkTransactionReference: Your reference for the network transaction.

For example:

{
  "networkTransactionReference": "123456789",
  "status": "RESERVE"
}

If we receive a FAIL response, we will allow the user to retry with the same or a new payment source (unless the error code maps to something non-retryable).

If there is a timeout or HTTP 500, the payment will cannot be tried again by the user. You will need to initiate a new payment request.

important

You must return a valid callback response within 20 seconds or the payment will fail.

Special features​

Most ePayment special features work with CARD_PASSTHROUGH without any PSP-specific changes. Add the feature's required fields to your create payment request alongside the standard cardPassthrough fields, and include the Psp-Id header as usual. The card callback and status update flow remain the same.

FeaturePSP support
ExpressSupported — see Express below
Personal QRSupported
One-time payment QRSupported
Profile sharingSupported
Minimum user ageSupported
Set order detailsSupported
Specify customer presentSupported
Add metadataSupported
Long-living paymentsSupported
Block payment sourcesSupported
Freestanding cardsNot applicable

For example, to use Minimum user age, add the minimumUserAge field to the create payment request. Vipps MobilePay verifies the user's age before they can proceed — your cardCallbackUrl is called as normal.

Express​

PSPs can use the Express feature with CARD_PASSTHROUGH. The user selects shipping options and shares their profile inside the app; your cardCallbackUrl is still called with the card token for you to process.

To enable it, add the following to your create payment request alongside the standard cardPassthrough fields:

  • profile.scope: "name address email phoneNumber" (all four values required)
  • shipping: either fixedOptions or dynamicOptions — see Shipping options

The amount is the base product price; Vipps MobilePay adds the selected shipping cost before the user confirms. After authorization, retrieve shippingDetails and userDetails from GET:/epayment/v1/payments/{reference} (include the Psp-Id header), then capture the full amount.

For full details on shipping options, dynamic callbacks, and button guidelines, see the Express feature guide.

More information​

  • How it works — visual flows for online, in-store, QR, and freestanding card payment scenarios
  • Payment operations — capture, cancel, refund, and more
  • ePayment API spec — the full technical specification for all endpoints, including required fields, data types, and valid formats
Last updated on