Skip to main content

ePayment API

For full ePayment API documentation, see the ePayment API section. This page covers the PSP-specific card passthrough additions.

Card passthrough​

Flowchart for ePayments with card passthrough.

Technicalities to note:

  • The card callback from the API is synchronous. We expect a response to the callback that tells us if the payment went through or not.
  • In case of failure the user can retry the card callback if the error response from the PSP allows it. A different card may be chosen for the retry.
  • We will treat an HTTP 500 error and timeouts on the callback as non-retryable payments.
    • The payments can be patched later, so we reflect if the payment actually became reserved.
    • We will show an error message like "check the payment status at the merchant you came from"

Initiate payment​

Send a POST:/epayment/v1/payments request that includes the new cardPassthrough property:

  • pspReference (required): Your unique reference for this payment.
  • cardCallbackUrl (required): URL where we will send the card token.
  • 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.

See the Create payment guide for explanation of the other required and optional fields.

Here is an example of what a typical bare-bones payment initiation will look like:

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": "string",
    "cardCallbackUrl": "https://example.com/psp-makepayment",
    "allowedCardTypes": [ "VISA_DEBIT", "VISA_CREDIT", "VISA_DANKORT", "MC_CREDIT", "MC_DEBIT"],
    "preferVisaPartOfVisaDankort": true,
    "publicEncryptionKeyId": "some-guid"
  },
  "reference": 2810171754658432260,
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "https://developer.vippsmobilepay.com/docs/example-pages/result-page",
  "paymentDescription": "Purchase of socks"
}'

Card callback​

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.

Last updated on