Skip to main content
When validation fails or a submit guard blocks payment, the widget emits an ERROR event before or instead of PAYMENT_ERROR. 
{
  type: 'ERROR';
  payload: {
    code: PaymentErrorCode;
    message: string;
    missingFields?: string[];  // present for VALIDATION_FAILED
  };
}

​
Payment submission codes

CodeWhenWhat to do
VALIDATION_FAILEDMissing or invalid card/fieldsShow message; check missingFields
PAYMENT_IN_PROGRESSSubmit already running or payment completedDisable pay button; wait or reset session
INVALID_MODEWrong method for current mode (e.g. submitPayment during upsell)Call submitUpsell() instead
NOT_READYWidget still loadingWait for READY
NO_CARD_FORMCard form hidden (wallet-only layout)Use wallet or wait for fallback UI
DUPLICATE_TRANSACTIONUpsell already charged for this initialPaymentSessionTreat as success; redirect (also emitted as its own event type)

​
Examples

​
Validation failed

// payload:
{
  code: 'VALIDATION_FAILED',
  message: 'Please complete all required fields',
  missingFields: ['email', 'cardNumber']
}

​
Wrong submit method

{
  code: 'INVALID_MODE',
  message: 'submitPayment is not available in upsell mode'
}

​
Missing upsell session

When usePreviousPaymentMethod: true without upsell.initialPaymentSession: 
{
  code: 'VALIDATION_FAILED',
  message: 'Initial session missing'
}

​
SDK initialization errors

Config and messaging errors use separate SDK ERROR_CODES (e.g. INVALID_CONFIG, COMMUNICATION_ERROR) and are passed to onError — not the ERROR event type above.