Checkout icon

PAN fallback for network tokens

Recover refused network token payments with an automatic retry on the underlying card number.

If you manage network tokens yourself and are fully PCI compliant, you can include the underlying Primary Account Number (PAN) in your payment request. When the issuer refuses the attempt with the network token, we can automatically retry the payment with the PAN. This helps you recover payments that would otherwise fail, without asking the shopper to enter their card details again.

The PAN fallback is enabled by default, sending the PAN is optional. To use the fallback, include the PAN in your payment request. If you do not include the PAN, we process the payment with the network token only.

Requirements

Before you begin, take into account the following requirements and limitations.

Requirement Description
Integration type An online payments integration where you manage network tokens yourself, that supports card payments, and uses Checkout API v69 or later.
Webhooks Subscribe to the Standard webhooks. To get data about the retry attempts we make, set up receiving retry attempt data in your Customer Area.
Limitations
  • The PAN fallback is only available in the live environment. You cannot test it in the test environment.
  • Not every refused payment leads to a retry with the PAN. Retries depend on the acquirer response code and on our optimization logic.
  • You cannot use 3D Secure for transactions with network tokens that you manage yourself.
  • You must be fully PCI compliant to send the PAN in payment requests.

How the PAN fallback works

When your payment request contains both a network token and the underlying PAN, we can make two authorization attempts:

  1. You send a payment request that contains the network token and the underlying PAN.
  2. We always attempt the payment with the network token first. If it succeeds, the authorization completes using the network token.
  3. If the attempt is refused with a retryable response code, and our optimization logic determines that a retry can succeed, we trigger the PAN fallback.
  4. We send a second authorization attempt with the PAN. The shopper does not have to do anything.
  5. You get the result of each attempt in the payment response and in the AUTHORISATION webhook.

If your payment request does not contain a PAN, we process the payment with the network token only, and your existing payment flow does not change.

Send a payment request with the PAN

To let us fall back to the PAN, send the network token and the underlying PAN in the same payment request.

  1. From your server, make a POST /payments request. Include the parameters that you need to make a payment with a network token, such as the mpiData object. To include the network token as well as the PAN, specify the following:

    Parameter name Description
    paymentMethod.type networkToken
    paymentMethod.expiryMonth The expiry month of the network token.
    paymentMethod.expiryYear The expiry year of the network token.
    paymentMethod.cvc Optional. The card verification code or security code.
    paymentMethod.holderName The name of the cardholder associated with the network token.
    paymentMethod.number The network token you get from the card network.
    paymentMethod.brand Optional. For co-badged network tokens in the US, the card network that you want to route the payment to.
    secondaryPaymentMethod.number The card number (PAN) associated with the network token.
    secondaryPaymentMethod.expiryMonth The expiry month of the card.
    secondaryPaymentMethod.expiryYear The expiry year of the card.
    secondaryPaymentMethod.holderName The name of the cardholder associated with the card.

  2. In the response, check the additionalData object for data about the attempts that we made.

Collect retry attempt data

To find out which attempts we made for a payment, set up receiving retry attempt data in your payment responses and webhooks.

To set up receiving retry attempt data:

  1. Log in to your Customer Area.
  2. Go to Developers > Additional data.
  3. In the Acquirer section, select Include the retry attempts.
  4. Select Save configuration.

Retry attempt data

When you collect retry attempt data, the additionalData object in your payment response contains a set of parameters for each attempt that we made. In the parameter names, attemptN is the number of the attempt: attempt1 for the attempt with the network token, and attempt2 for the attempt with the PAN.

Parameter name Description
retry.attemptN.acquirer The name of the acquirer that processed the attempt.
retry.attemptN.acquirerAccount The acquirer account that was used for the attempt.
retry.attemptN.responseCode The numeric acquirer response code from the card network.
retry.attemptN.rawResponse The details of the raw unmodified response from the acquirer.

The AUTHORISATION webhook contains the same information as the additionalData object from your payment response.

The following examples show the additionalData object for each possible outcome.

See also