Error Handling & Failure States

When implementing custom layouts, you need to handle payment failures and display appropriate error messages to your users. This guide covers the available options and best practices.

Two types of errors

Before implementing error handling, it’s important to understand the difference between validation errors and payment failures:

Type	When it occurs	How it’s handled
Validation errors	During form input (invalid card number, missing fields)	Handled automatically by input components; prevents form submission
Payment failures	After form submission (declined card, insufficient funds)	Requires explicit handling with error container or custom code

There’s also a third case — the SDK itself failing to start (e.g. an invalid client token) before any form is even shown. See SDK initialization failures below.

Not all failures are retryable

Before prompting the user to try again, be aware of two important characteristics of payment failures: A client-side failure doesn’t always mean the payment failed. A failure reported by the SDK can be local to the browser or device — for example, a network drop after the payment was submitted. In that case the payment may have completed successfully even though the client saw an error. Your server — through payment webhooks or the Payments API — is the source of truth for the payment’s status. Verify the status server-side before asking the user to pay again, otherwise you risk charging them twice. Decline reasons are intentionally generic. When a payment is declined, the SDK reports that it failed, but not the specific reason. This is deliberate to avoid leaking details. The detailed reason is available to you server-side via webhooks, the Payments API, and the Primer Dashboard. In practice: show a generic failure message, offer the user a way to retry or choose another payment method, and treat your server-side payment status — not the client-side error — as the definitive outcome.

Deciding whether to retry (Web)

The failure payload tells you which case you’re dealing with. The error on the primer:payment-failure event carries a code identifying the failure, and an origin that says who should act on it:

`origin`	What happened	Before offering a retry
`payment`	The payment reached Primer and failed or was declined	Safe to offer a retry — it creates a new payment attempt. Look up the decline reason server-side or in the Dashboard
`network`	An API request failed at the transport level (timeout, dropped connection, server error)	The outcome is unknown — the payment may have succeeded. Verify the payment status server-side first, or you risk a double charge
`primer`	The payment ended in a state the SDK can’t interpret	Verify the payment status server-side; share the `diagnosticsId` with Primer support if the state is unclear
`user`	The shopper cancelled	Safe to let the shopper try again
`integration`	Your integration passed something invalid	Fix the integration — the error’s `suggestion` says how. Retrying won’t help

In short: on a network failure, ask your backend whether a payment was created — the SDK couldn’t tell. On any other failure, use payment.id (when present) to cross-check the status and cause with your backend before deciding whether to allow a retry.

checkout.addEventListener('primer:payment-failure', async (event) => {
  const { error, payment } = event.detail;

  if (error.origin === 'network') {
    // The SDK couldn't determine whether a payment was created.
    // Your backend knows — through Primer webhooks or the Payments API.
    const { succeeded } = await checkPaymentStatusOnYourBackend({
      orderId: myOrderId,
    });
    if (succeeded) {
      window.location.href = '/order-confirmation';
      return;
    }
    showRetryMessage();
    return;
  }

  // The payment failed. When `payment` is present, its `id` identifies the
  // failed payment — cross-check the status and decline reason with your
  // backend before deciding whether to offer a retry.
  showRetryMessage();
});

The failure payload’s payment carries only id, orderId, and summary payment method data — not the payment’s status. Look the status up by id through your backend, the Payments API, or the Dashboard.

On SDK versions without origin (before 1.6.2 at the top level; 1.6.2 to 1.9.2 expose it nested at error.data.error.origin), you can’t detect a transport-level failure from the error itself. Use the presence of payment data instead: a failure without payment may be network-caused — a payment may still have been created, so verify with your backend before retrying. A failure with payment identifies the payment to cross-check by id.

Default error behavior

Web
Android
iOS

The <primer-error-message-container> specifically handles payment failures that occur after form submission, not card validation errors. Card validation is handled by the input components themselves and prevents form submission until valid.

The Primer Checkout SDK handles most error scenarios automatically. Payment failures are displayed in the checkout UI, and validation errors appear inline on form fields.Form validation includes:

Card number validation (Luhn check, network detection)
Expiry date validation (format, future date)
CVV length validation (based on card network)
Required field validation (cardholder name, billing address)

Errors appear when the user leaves a field (on blur), not while typing.When a payment fails, the SDK:

Emits PrimerCheckoutState.Failure with error details on checkout.state
Displays a default error screen (in PrimerCheckoutSheet)
Offers retry and “try other methods” options

The Primer Checkout SDK handles most error scenarios automatically. Validation errors appear inline on form fields, and payment failures are displayed in the checkout UI.Form validation includes:

Card number validation (Luhn check, network detection)
Expiry date validation (format, future date)
CVV length validation (based on card network)
Required field validation (cardholder name, billing address)

When a payment fails, the SDK:

Reports the error via onCompletion
Displays a default error screen
Offers retry options

Built-in error display

Web
Android
iOS

The <primer-error-message-container> provides a convenient way to display payment failures without writing custom code:

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-error-message-container></primer-error-message-container>
    </div>
  </primer-main>
</primer-checkout>

<primer-checkout client-token="your-token">
  <div slot="main" id="custom-checkout">
    <div id="payment-methods">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-error-message-container></primer-error-message-container>
    </div>
  </div>
</primer-checkout>

For optimal user experience, place the error container:

Prominently where it will be visible after a payment attempt
Near the action where users will naturally look for feedback after submitting payment
In context within the same visual area as the payment method it relates to

PrimerCheckoutSheet displays a default error screen automatically when a payment fails. No additional code is required for basic error handling.To react to a failure in your own code, observe checkout.state and match on PrimerCheckoutState.Failure:

val state by checkout.state.collectAsStateWithLifecycle()

LaunchedEffect(state) {
    val s = state
    if (s is PrimerCheckoutState.Failure) {
        val error = s.primerError
        Log.e("Checkout", "Payment failed: ${error.description}")
        Log.e("Checkout", "Error code: ${error.errorCode}")
        Log.e("Checkout", "Diagnostics ID: ${error.diagnosticsId}")
    }
}

PrimerCheckoutSheet(checkout = checkout)

Looking up a failed payment

When the payment was created before it failed — a decline, for example — Failure also carries checkoutData, so you can look the payment up on your backend or show the merchant reference on your error screen:

if (s is PrimerCheckoutState.Failure) {
    val payment = s.checkoutData?.payment
    if (payment != null) {
        reportFailedPayment(paymentId = payment.id, orderId = payment.orderId)
    }
}

checkoutData is null when the failure happened before a payment existed — session initialization, tokenization or connectivity problems — so always treat it as optional. It never carries the processor decline reason.

Payment failures are reported through the onCompletion callback. The SDK also displays a default error screen automatically:

PrimerCheckout(clientToken: clientToken) { state in
  if case let .failure(error) = state {
    print("Error ID: \(error.errorId)")
    print("Description: \(error.localizedDescription)")
    print("Diagnostics ID: \(error.diagnosticsId)")
  }
}

Error properties

Every error from the SDK includes diagnostic information to help identify and resolve issues.

Web
Android
iOS

Property	Description
`code`	Error code identifying the failure type (e.g. `PAYMENT_FAILED`, `REQUEST_TIMEOUT`, `SERVER_ERROR`)
`message`	Human-readable error message
`diagnosticsId`	Reference ID for Primer support. For failed API requests, this is the request’s `X-Request-Id`, which Primer also logs server-side
`origin`	Who should act on the failure: `payment`, `network`, `primer`, `user`, or `integration` — see Deciding whether to retry
`suggestion`	How to fix the error, present on `integration`-origin errors

Property	Type	Description
`errorId`	`String`	Unique error identifier
`description`	`String`	Human-readable error message
`errorCode`	`String?`	Error code (e.g., `"card_declined"`)
`diagnosticsId`	`String`	Reference ID for support
`recoverySuggestion`	`String?`	Suggested recovery action

Property	Type	Description
`errorId`	`String`	Stable, kebab-case identifier for the error category (use for programmatic branching)
`diagnosticsId`	`String`	Unique per-occurrence diagnostics ID to share with Primer support
`recoverySuggestion`	`String?`	Suggested recovery action, when one applies
`errorDescription`	`String?`	Human-readable description for logging (also available as `localizedDescription`)

Custom error handling

Web
Android
iOS

You can implement your own payment failure handling using the SDK callbacks and events. Choose one of the following approaches:

Payment events (recommended)
State change event

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment } = event.detail;
  document.getElementById('my-custom-error').style.display = 'none';
  window.location.href = `/order/confirmation?id=${payment.orderId}`;
});

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error, payment, paymentMethodType } = event.detail;
  const customErrorElement = document.getElementById('my-custom-error');
  customErrorElement.textContent = error.message;
  customErrorElement.style.display = 'block';

  console.error('Payment failed:', {
    code: error.code,
    message: error.message,
    diagnosticsId: error.diagnosticsId,
    origin: error.origin,
  });
});

Before showing a retry option in this handler, check the error’s code and origin — see Deciding whether to retry.

The onPaymentSuccess and onPaymentFailure callbacks on the primer:ready instance still work, but are deprecated in favor of the primer:payment-success and primer:payment-failure events.

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:state-change', (event) => {
  const { primerJsError, paymentFailure } = event.detail;

  if (primerJsError || paymentFailure) {
    const customErrorElement = document.getElementById('my-custom-error');
    const errorMessage = primerJsError?.message || paymentFailure?.message;
    customErrorElement.textContent = errorMessage;
    customErrorElement.style.display = 'block';
  } else {
    document.getElementById('my-custom-error').style.display = 'none';
  }
});

This approach gives you complete control over payment failure presentation but requires you to implement the error handling logic yourself.

Override the default error screen in PrimerCheckoutSheet with a custom Composable:

PrimerCheckoutSheet(
    checkout = checkout,
    error = { primerError, checkoutData ->
        Column(
            modifier = Modifier
                .fillMaxWidth()
                .padding(24.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
        ) {
            Icon(
                imageVector = Icons.Default.Warning,
                contentDescription = null,
                tint = MaterialTheme.colorScheme.error,
                modifier = Modifier.size(48.dp),
            )
            Spacer(Modifier.height(16.dp))
            Text(
                text = "Payment failed",
                style = MaterialTheme.typography.titleLarge,
            )
            Spacer(Modifier.height(8.dp))
            Text(
                text = primerError.description,
                style = MaterialTheme.typography.bodyMedium,
                textAlign = TextAlign.Center,
            )
            checkoutData?.payment?.id?.let { paymentId ->
                Spacer(Modifier.height(8.dp))
                Text(
                    text = "Payment reference: $paymentId",
                    style = MaterialTheme.typography.bodySmall,
                    textAlign = TextAlign.Center,
                )
            }
            Spacer(Modifier.height(24.dp))
            Button(onClick = { checkout.dismiss() }) {
                Text("Try again")
            }
        }
    },
)

Observing validation state

For inline components, observe card form validation directly:

val cardFormController = rememberCardFormController(checkout)
val formState by cardFormController.state.collectAsStateWithLifecycle()

val errors = formState.fieldErrors
errors?.forEach { error ->
    Log.d("Validation", "${error.inputElementType}: ${error.errorId}")
}

PrimerCheckout renders the managed error screen and does not expose screen slots. For full control over how a payment failure is presented, build your own layout from the composable views, drive it with a PrimerCheckoutSession, and handle the terminal .failure state in the .primerCheckoutSession(_:onCompletion:) completion closure:

struct CheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession
  @State private var errorMessage: String?

  init(clientToken: String) {
    _session = StateObject(wrappedValue: PrimerCheckoutSession(clientToken: clientToken))
  }

  var body: some View {
    ScrollView {
      PrimerCardForm()

      if let errorMessage {
        VStack(spacing: 20) {
          Image(systemName: "xmark.circle.fill")
            .font(.system(size: 48))
            .foregroundColor(.red)
          Text("Something went wrong")
            .font(.title3.weight(.semibold))
          Text(errorMessage)
            .font(.body)
            .foregroundColor(.secondary)
            .multilineTextAlignment(.center)
        }
        .padding()
      }
    }
    .primerCheckoutSession(session) { state in
      if case let .failure(error) = state {
        errorMessage = error.recoverySuggestion ?? "Please try again."
        print("Checkout failed [\(error.errorId)] — diagnosticsId: \(error.diagnosticsId)")
      }
    }
  }
}

For UIKit integrations, the same PrimerError arrives through PrimerCheckoutPresenterDelegate’s primerCheckoutPresenterDidFailWithError(_:) callback.

Observing validation state

The card form is driven by PrimerCardFormSession, which publishes PrimerCardFormState. Observe it inside a PrimerCardForm slot to read validation errors per field:

PrimerCardForm(
  cardDetails: { session in
    VStack(alignment: .leading) {
      CardFormDefaults.cardNumber(session)
      if session.state.hasError(for: .cardNumber),
         let message = session.state.errorMessage(for: .cardNumber) {
        Text(message).foregroundColor(.red)
      }
    }
  }
)

To inspect every current field error, iterate state.fieldErrors:

ForEach(session.state.fieldErrors) { error in
  Text("\(error.fieldType): \(error.message)")
}

Field presence is Dashboard-driven through CardFormConfiguration, and validation runs automatically as the shopper edits each field — gate your submit button on session.state.isValid.

SDK initialization failures

Before checkout can process payments, the SDK needs to initialize — validate the client token, load your Checkout Builder configuration, etc. Treat a failure here separately from the validation and payment errors above: no form has been shown yet, so there’s nothing to retry other than re-initializing the SDK.

This section covers Web. See Default error behavior above for Android and iOS.

When <primer-checkout> fails to initialize, <primer-main> renders its checkout-error slot instead of the payment methods. Provide your own content there to replace the default error screen:

<primer-checkout client-token="...">
  <primer-main slot="main">
    <div slot="checkout-error">
      We could not load the checkout. Please try again later.
    </div>
  </primer-main>
</primer-checkout>

For error details — to log the failure or branch on its cause — listen for primer:state-change and read primerJsError:

document.addEventListener('primer:state-change', (e) => {
  const { primerJsError } = e.detail;
  if (primerJsError) {
    console.error(primerJsError.code, primerJsError.message);
  }
});

Property	Description
`code`	Stable identifier for the failure: `INVALID_CLIENT_TOKEN` (the token is malformed, expired, or was rejected — generate a new one) or `INITIALIZATION_ERROR` (any other initialization failure, e.g. your configuration failed to load)
`message`	Human-readable error message
`suggestion`	Suggested recovery action, when one applies

If you bypass <primer-main> with a custom slot="main" on <primer-checkout>, handle primerJsError the same way.

Choosing the right approach

Approach	Best for	Trade-offs
Built-in error display	Quick implementation, consistent styling	Less customization control
Custom error handling	Full control over UX and design	More code to maintain

Best practices

Always handle errors - Never leave users without feedback after a failed payment
Be specific where you can - Validation errors can name the exact problem; payment declines are intentionally generic, so pair them with actionable next steps instead
Provide next steps - Guide users on how to resolve the issue (try another card, check details, etc.)
Verify before retrying - Confirm the payment status server-side before treating a client-side failure as final; the payment may have succeeded. On Web, branch on the error’s code and origin
Clear on retry - Hide error messages when users attempt a new payment
Log for debugging - Capture error details including diagnosticsId for troubleshooting

Error message container

Web component SDK reference

Android SDK reference

Android SDK API documentation

Events guide

Complete reference for all checkout events

Log Errors Guide

Capture and log payment errors for debugging

​Two types of errors

​Not all failures are retryable

​Deciding whether to retry (Web)

​Default error behavior

​Built-in error display

​Looking up a failed payment

​Error properties

​Custom error handling

​Observing validation state

​Observing validation state

​SDK initialization failures

​Choosing the right approach

​Best practices

​See also

Error message container

Android SDK reference

Events guide

Log Errors Guide

Two types of errors

Not all failures are retryable

Deciding whether to retry (Web)

Default error behavior

Built-in error display

Looking up a failed payment

Error properties

Custom error handling

Observing validation state

Observing validation state

SDK initialization failures

Choosing the right approach

Best practices

See also