ePayment PSP API guide

Coming soon

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

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. For full ePayment API documentation, see the ePayment API.

Overview

With CARD_PASSTHROUGH, the payment flow differs from the standard WALLET or CARD payment methods:

1. You create a payment with paymentMethod.type: CARD_PASSTHROUGH and a cardPassthrough object specifying your callback URL.
2. The user is redirected to the Vipps MobilePay app and selects a card.
3. Vipps MobilePay sends the card token to your cardCallbackUrl synchronously.
4. You process the payment using your own payment processing systems and respond within 20 seconds.
5. The user is redirected to your returnUrl.

Create a payment

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.

Before creating payments, implement your card callback endpoint. Vipps MobilePay calls it synchronously after the user confirms payment and expects a response within 20 seconds.

Send a create payment request with the following settings:

• Add the Psp-Id header with your PSP identifier
• Set paymentMethod.type to CARD_PASSTHROUGH
• Include the cardPassthrough object, filled out
  • pspReference (required): Your unique reference for this payment.
  • cardCallbackUrl (required): URL where we will send the card token. See card callback for the expected request and response format.
  • cardCallbackAuthHeader (required): Authentication header value for the callback.
  • allowedCardTypes: Card types the user can select. Values: VISA_DEBIT, VISA_CREDIT, VISA_DANKORT, DANKORT, MC_CREDIT, MC_DEBIT. If not specified, all types are allowed.
  • preferVisaPartOfVisaDankort: When true, prefer the Visa part of a Visa/Dankort co-branded card. Default: false.

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" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-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", "VISA_DANKORT", "MC_CREDIT", "MC_DEBIT"]
  },
  "reference": "acme-shop-123-order123abc",
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "https://example.com/redirect?orderId=1512202",
  "paymentDescription": "Purchase of socks"
}'

When the user confirms a payment or agreement in the Vipps MobilePay app and selects their card, we send a POST request to your cardCallbackUrl with the card token. You must respond synchronously with the payment status within 20 seconds. See card callback for details.

Card callback

When the user confirms the payment in the Vipps MobilePay app and selects their card, we send a POST request to your cardCallbackUrl with the card token or PAN. You must respond synchronously with the payment result within 20 seconds.

Key behaviors:

• The callback is synchronous — we expect a response telling us whether the payment went through or not.
• If the PSP returns 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 patched 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"
}

Callback response

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

• status (required): The payment result. One of:
  • RESERVE — Payment reserved successfully.
  • CAPTURE — Payment captured immediately. Use this if processing as a sale, or if you are certain you will capture.
  • FAIL — Payment failed. Include error reason and error codes so we can show a meaningful message to the user.
  • 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). More information about error cases and soft decline will come later.

Authentication

HMAC authentication will be added to the callbacks. More information will come.

Update the payment information

Use the POST:/epayment/v1/payments/{reference}/capture endpoint to update the status for us.

MORE INFORMATION TO BE PROVIDED

Related ePayment features

For the full range of options available on the create payment endpoint, see:

• Create payment guide
• Available features