Skip to main content

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.

Last updated on