Error codes

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

Code	When	What to do
`VALIDATION_FAILED`	Missing or invalid card/fields	Show `message`; check `missingFields`
`PAYMENT_IN_PROGRESS`	Submit already running or payment completed	Disable pay button; wait or reset session
`INVALID_MODE`	Wrong method for current mode (e.g. `submitPayment` during upsell)	Call `submitUpsell()` instead
`NOT_READY`	Widget still loading	Wait for `READY`
`NO_CARD_FORM`	Card form hidden (wallet-only layout)	Use wallet or wait for fallback UI
`DUPLICATE_TRANSACTION`	Upsell already charged for this `initialPaymentSession`	Treat 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.

Events reference Troubleshooting

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Payment submission codes

Examples

Validation failed

Wrong submit method

Missing upsell session

SDK initialization errors

​Payment submission codes

​Examples

​Validation failed

​Wrong submit method

​Missing upsell session

​SDK initialization errors

​Related

Payment submission codes

Examples

Validation failed

Wrong submit method

Missing upsell session

SDK initialization errors

Related