Skip to main content

Error Codes

The following is a list of Purse Headless Checkout SDK error codes, their descriptions, additional payload and occasionally information about how to resolve them. Every PurseHeadlessCheckoutError object links to this list in its documentationLink attribute

BRAND_NOT_BELONGS_TO_DETECTED​

Description​

This error indicates that the brand you are trying to set does not belong to the detected brands for the card.

Additional Payload​

An object containing the brand information:

{
  brand: CardScheme;
  detectedBrands: CardScheme[];
}

ELEMENT_NOT_FULFILLED​

Description​

This error indicates happens when you try to set a primary method as the primary source of payment and indicates that this source is not fulfilled.

Additional Payload​

type additionalPayload = never;

ELEMENT_RENDER_FAILED​

Description​

This error is thrown when an error occurs while rendering a payment element.

Additional Payload​

type additionalPayload = {
  error: {
    message: string;
    stack: string;
  }
};

EXPIRED_SESSION​

Description​

This error indicates that the provided client session has expired. See Create a Client Session to generate a new session and Client Session Reference to learn more about Client Session.

Additional Payload​

type additionalPayload = never;

FAILED_TO_ADD_TOKEN​

Description​

This error indicates that the attempt to add a new token has failed.

Additional Payload​

type additionalPayload = never;

FAILED_TO_DELETE_ALL_TOKENS​

Description​

This error indicates that the attempt to delete all tokens has failed.

Additional Payload​

type additionalPayload = {
  error: {
    message: string;
    stack: string;
  }
};

FAILED_TO_INIT_SECONDARY_TOKEN​

Description​

This error indicates that the initialization of a secondary payment token (gift card, voucher, ANCV account…) has failed. For methods requiring a customer action, such as ANCV, it is also thrown when the partner returns an unexpected state.

Additional Payload​

type additionalPayload = never;

TOKEN_ALREADY_EXISTS​

Description​

This error indicates that the token already exists.

Additional Payload​

type additionalPayload = never;

TOKEN_NAME_EXISTS​

Description​

This error indicates that the initialization of a secondary method token has failed.

Additional Payload​

type additionalPayload = never;

INVALID_INIT_PARAMS​

Description​

This error indicates that the initialization parameters provided to the createHeadlessCheckout method are invalid. Ensure that all required parameters are provided and correctly formatted.

Additional Payload​

Missing parameters will be listed in the additional payload.

type additionalPayload = string;

INVALID_LOAN_SIMULATION​

Description​

This error indicates that the loan simulation is either not available or failed.

Additional Payload​

type additionalPayload = never;

INVALID_TAKE_AMOUNT​

Description​

This error indicates that you are trying to perform a take operation on a secondary token with an invalid amount.

Additional Payload​

An object containing detailed information about the invalid amount:

{
  message: string;
  amount: number;
  balance?: number;
  sessionAmount?: number;
}

INVALID_TOKEN_NAME​

Description​

This error indicates that the token name you are trying to use is invalid. Ensure that the token name meets the required format and length (/^[a-zA-Z0-9\s]{1,25}$/).

Additional Payload​

type additionalPayload = never;

MAX_AMOUNT_EXCEEDED​

Description​

This error indicates that the transaction amount exceeds the maximum amount allowed for the selected payment method. The payment method has a payment_max_amount configuration that prevents transactions above a certain threshold.

Additional Payload​

type additionalPayload = string;

METHOD_DISABLED​

Description​

This error is thrown when you attempt to render a payment element (using appendTo() or render()) for a payment method that is currently disabled. A method can be disabled for several reasons, such as not meeting minimum amount requirements or exceeding maximum amount limits.

if (method.disabled.value) {
  console.log('Method disabled:', method.disabled.value.code);
  // Possible codes: MIN_AMOUNT_NOT_MET, MAX_AMOUNT_EXCEEDED
}

Additional Payload​

An object containing the disabled state information:

{
  code: string;
  message: string;
}

METHOD_NOT_IMPLEMENTED​

Description​

This error indicates that you are trying to invoke a method that is not implemented on the object.

Additional Payload​

type additionalPayload = never;

METHOD_IS_NOT_SIMULABLE​

Description​

This error indicates that loan simulation is not available for this partner/method combination.

Additional Payload​

type additionalPayload = never;

METHOD_NOT_REGISTERABLE​

Description​

This error indicates that saveToken is not enabled on the method experience.

Additional Payload​

type additionalPayload = never;

MISSING_SESSION​

Description​

This error indicates that the payment session is missing. Ensure that your PurseHeadlessCheckout instance is initialized correctly with a Client Session.

Additional Payload​

type additionalPayload = string | undefined;

MISSING_TOKEN​

Description​

This error indicates that you are trying to use a token that does not exist. Ensure that the token ID you are using is correct and that the token has been successfully registered before attempting to use it.

Additional Payload​

type additionalPayload = never;

MISSING_WALLET_SESSION​

Description​

This error indicates that the wallet session is missing. Ensure that the wallet system is correctly configured on your Entity.

Additional Payload​

type additionalPayload = never;

MIN_AMOUNT_NOT_MET​

Description​

This error indicates that the transaction amount is below the minimum amount required for the selected payment method. The payment method has a payment_min_amount configuration that prevents transactions below a certain threshold.

Payment methods are automatically filtered based on the transaction amount, and this error will be reflected in the disabled state of the method.

Additional Payload​

type additionalPayload = string;

NOT_SUPPORTED_BRAND​

Description​

This error indicates that the brand is not supported for this payment method.

Additional Payload​

An object containing brand information:

{
  brand: CardScheme;
  detectedBrands?: CardScheme[] | null;
  supportedBrands: CardScheme[];
}

ON_BEFORE_VALIDATE_HOOK_FAILED​

Description​

This error indicates that the onBeforeValidate hook has failed.

Additional Payload​

type additionalPayload = {
  error: {
    message: string;
    stack: string;
  }
};

OTHER_TRANSACTION_PENDING_FOR_ACCOUNT​

Description​

This error indicates that another transaction is already pending on the customer account. It is returned by ANCV when a previous confirmation request is still open in the ANCV mobile app: the customer must cancel it before retrying.

Additional Payload​

type additionalPayload = never;

PAYMENT_METHOD_NOT_FOUND​

Description​

This error indicates that you are trying to perform an action with an unknown payment method.

Additional Payload​

An object containing payment method identification:

{
  partner: Partner;
  method: Method;
  session: string;
}

PAYMENT_NOT_FULFILLED_ON_SUBMIT​

Description​

This error indicates that you are trying to submit a payment but the payment form is not fulfilled yet.

Additional Payload​

type additionalPayload = never;

PAYMENT_TOKEN_NOT_FOUND_IN_SESSION​

Description​

This error indicates that the token is not found in the current session.

Additional Payload​

An object containing token identification:

{
  partner: Partner;
  method: Method;
  uniqueness_token: string;
}

POST_VALIDATE_FAILED​

Description​

This error indicates that the postValidate step of the payment process has failed.

Additional Payload​

type additionalPayload = never;

SECONDARY_METHOD_REQUEST_ABORTED​

Description​

This error indicates that the AbortSignal passed to getSecondaryToken was aborted before the token could be created. It happens on customer-action flows such as ANCV, where you can cancel the wait while the customer is asked to confirm in the mobile app.

Additional Payload​

type additionalPayload = never;

SECONDARY_METHOD_REQUIRED_CVV​

Description​

This error indicates that the CVV is missing for the selected secondary payment method.

Additional Payload​

type additionalPayload = never;

SECONDARY_METHOD_WRONG_CVV_FORMAT​

Description​

This error indicates that the CVV format is incorrect for the selected secondary payment method.

Additional Payload​

type additionalPayload = never;

SECONDARY_METHOD_WRONG_PAN_FORMAT​

Description​

This error indicates that the PAN format is incorrect for the selected secondary payment method.

Additional Payload​

type additionalPayload = never;

SECONDARY_METHOD_TAKE_POLICY_VIOLATED​

Description​

This error indicates that the method has a strict take policy and cannot be used with any amount.

Additional Payload​

type additionalPayload = never;

SECONDARY_TOKEN_EMPTY_BALANCE​

Description​

This error indicates that the giftcard/voucher token has an empty balance.

Additional Payload​

type additionalPayload = never;

SESSION_ALREADY_SET​

Description​

This error indicates that you are trying to set the same session twice.

Additional Payload​

type additionalPayload = never;

SESSION_MALFORMED​

Description​

This error indicates that the provided session could not be parsed or is malformed.

Additional Payload​

An object containing error details:

{
  message: string;
}

SET_WALLET_SESSION_FAILED​

Description​

This error indicates that setting the wallet session has failed. Ensure that the wallet system is correctly configured on your Entity.

Additional Payload​

The message and stack trace from the original error are forwarded in the additional payload.

type additionalPayload = {
  error: {
    message: string;
    stack: string;
  }
};

TOKEN_NAME_EXISTS​

Description​

This error indicates that the token name you are trying to use already exists. Ensure that you are using a unique name when registering a new token or editing an existing one.

Additional Payload​

type additionalPayload = never;

TOKEN_NOT_REGISTERABLE​

Description​

This error indicates that the token is not registerable. Ensure that the payment method supports tokenization and that the wallet system is correctly configured on your Entity.

Additional Payload​

type additionalPayload = never;

TOKEN_NOT_REGISTERED​

Description​

This error indicates that the token is not registered and thus making the action you are trying to perform not possible. Ensure that the token has been successfully registered before attempting to use it.

Additional Payload​

type additionalPayload = never;

UI_VALIDATION_FAILED_ERROR​

Description​

This error indicates that the preValidate step of the payment process has failed.

Additional Payload​

type additionalPayload = never;

UNKNOWN_ERROR​

Description​

This error indicates that an unknown error has occurred.

Additional Payload​

An object containing detailed error information:

{
  message: string;
  error: {
    message: string;
    stack?: string;
  };
}

USAGE_LIMIT_ERROR​

Description​

This error indicates that a usage limit has been reached for a secondary payment method.

Additional Payload​

type additionalPayload = {
  partner: string;
  method: string;
};

USER_ACTION_REQUEST_ABORTED_BY_CUSTOMER​

Description​

This error indicates that the customer refused the action requested on their side. With ANCV, the customer declined the confirmation in the ANCV mobile app. Treat it as a warning: the customer can retry immediately.

Additional Payload​

type additionalPayload = never;

USER_ACTION_REQUEST_HAS_EXPIRED​

Description​

This error indicates that the action requested from the customer was not executed within the allowed time. With ANCV, the confirmation in the mobile app did not happen within 5 minutes. Treat it as a warning: the customer can retry immediately.

Additional Payload​

type additionalPayload = never;

VALIDATE_FAILED​

Description​

This error indicates that the validate step of the payment process has failed.

Additional Payload​

An object containing validation error details:

{
  message: string;
}