active_attempt.next_action.type on the returned intent. Depending on the type, you either show something to the customer and wait, or collect input from the customer and call confirm or authorize.
Confirm vs. authorize
Two endpoints accept the customer’s input:
Both accept the same optional body fields:
otp (string, max 10 characters) and confirmation_data (object). Both return the updated payment intent.
Action types
none
The attempt is processing. No customer action is required.
Wait for the webhook or poll the intent.
approve_on_phone
The customer must approve the payment on their phone (e.g. via a USSD prompt or an in-app notification from their provider).
Display the instructions to the customer. The attempt resolves asynchronously — do not call confirm. Wait for the webhook or poll.
collect_otp
The customer has received a one-time password (e.g. via SMS) and must enter it.
Collect the OTP from the customer and call confirm or authorize:
redirect_to_url
The customer must visit an external URL to complete payment (e.g. a 3DS page or a provider-hosted form).
If
can_auto_redirect is true, redirect immediately. Otherwise, show a “Continue to payment” button. After the redirect returns, check the intent status or wait for the webhook. Do not call confirm.
embed_iframe
Embed a provider-hosted page within your UI.
Render an
<iframe> pointing at url. The attempt resolves when the customer completes the flow inside the iframe. Wait for the webhook or poll. Do not call confirm.
scan_qr_code
The customer must scan a QR code with their device.
Display the QR code using
image_url or render it from content. The attempt resolves asynchronously once the customer completes the payment in their app. Do not call confirm.
display_payment_instructions
Show the customer a set of structured instructions (e.g. a bank transfer reference).
Render all fields. The attempt resolves asynchronously once the provider confirms receipt. Do not call confirm.
complete_with_sdk
A provider SDK must run in the browser to complete the payment (e.g. to handle a native 3DS challenge).
Load the SDK from
sdk_url, initialise it with public_key and client_params, and mount it into the element with container_id. Once the SDK completes and provides a reference, call confirm or authorize with that reference in confirmation_data.
complete_with_sdk is the only action type (besides collect_otp) that requires a confirm or authorize call. All others resolve without one.