Skip to main content

ePayment API PSP

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.

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

Last updated on