PrimerClientError

PrimerClientError is the type of errors returned by the SDK. Each error is described by an error code and description it may include contextual information.

Not all failures are retryable

Before prompting the user to retry after an error, keep two things in mind:

A client-side error doesn’t always mean the payment failed. An error like PAYMENT_FAILED or PRIMER_SERVER_ERROR can be caused by conditions local to the browser — for example, a network drop after the payment was submitted. In that case the payment may have completed successfully even though the SDK reported a failure. 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, PAYMENT_FAILED doesn’t carry the specific decline 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.

Deciding whether to retry

PrimerClientError doesn’t say whether the failure happened in transit, so use the presence of payment data in onCheckoutFail instead. A failure without payment may be network-caused — a payment may still have been created, so ask your backend before retrying. A failure with payment identifies the failed payment: cross-check its status and decline reason by payment.id before deciding whether to offer a retry.

onCheckoutFail(error, { payment }, handler) {
  if (!payment) {
    // No payment data — the failure may be network-level and a payment
    // may still have been created. Check with your backend (which listens
    // to Primer webhooks) before letting the user pay again.
  } else {
    // `payment.id` identifies the failed payment. Cross-check its status
    // and decline reason with your backend before offering a retry.
  }

  if (!handler) {
    return;
  }
  return handler.showErrorMessage();
}

Properties

Hide Properties

code · string

An error code that matches one in the table below.

description · string

A brief description of the error.

data · object

A field containing contextual data related to the error.

diagnosticsId · string

A unique ID for the error instance, used internally by the SDK.

Error Codes, Descriptions and Recovery Suggestions

Error Code	Description	Recovery Suggestion
NO_PAYMENT_METHODS
PRIMER_TEARDOWN		N/A
PRIMER_SERVER_ERROR		Check the description for HTTP error information.
THREE_DS_AUTH_FAILED	Happens when ThreeDS authentication failed.	Check the error description for details.
TOKENIZATION_ERROR		Check the error message returned during tokenization.
DUPLICATE_PAYMENT_METHOD_ERROR	Indicates that the payment method is already vaulted.
CARD_NUMBER_ERROR	Indicates the provided card number is invalid.	Display a validation error to the user.
RESUME_ERROR	Indicates that the merchant cancelled the payment.	N/A - merchant initiated.
VALIDATION_ERROR		Display a validation error to the user.
PAYMENT_FAILED	Payment failed after tokenization.	Check the error for details on what went wrong.
PAYMENT_CREATION_ABORTED	Payment creation was aborted prior to completion.	N/A - merchant initiated.
PAYMENT_CREATION_DISABLED
CLIENT_SESSION_UPDATE_ERROR	Failed to update the client session details.
INVALID_ARGUMENT	Invalid information was passed when initialising SDK.	Check the error for which argument(s) need updating.
VAULT_FETCH	Indicates a failure to fetch vaulted payment methods.	Check network connection and client session.
VAULT_DELETE	Indicates failure to delete a vaulted payment method.	Check that the method hasn’t already been deleted.
HEADLESS_VAULT_MANAGER_VALIDATION		Check that the method exists in the vault.
CARD_FORM_VALIDATION_UNEXPECTED_FIELD	The field was not defined for the payment method.	Removed the field and re-submit the payment.
MISSING_FIRST_NAME_OR_LAST_NAME	For Apple Pay, indicates a missing name field.	The user must provide both names in their Apple wallet.
IDEMPOTENCY_KEY_ALREADY_EXISTS	A payment with the provided idempotency key already exists.	Use a unique idempotency key for each payment request.