Payment intents

A payment intent is one payment to take, whatever the method. Create it with the amount, confirm it with the customer's chosen method, and the customer acts next: a QR code to scan, a cash reference to pay at a collection location, or a payment page to visit. You can create and confirm in one call with confirm: true.

The calls are Create a payment intent, Confirm a payment intent, Cancel a payment intent, Retrieve a payment intent and List payment intents. Creating, confirming and cancelling each require an Idempotency-Key header.

requires_payment_method

requires_confirmation

requires_action

processing

succeeded

canceled

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

requires_payment_method

requires_confirmation

requires_action

processing

succeeded

canceled

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

How a payment intent's status changes. Its states: requires_payment_method, requires_confirmation, requires_action, processing, succeeded (final), canceled (final).

1. requires_payment_method to requires_action
2. requires_confirmation to requires_action
3. requires_action to processing
4. processing to succeeded
5. requires_action to requires_payment_method: attempt failed
6. processing to requires_payment_method: attempt failed
7. requires_payment_method to canceled
8. requires_confirmation to canceled
9. requires_action to canceled

Status	When
requires_payment_method	No method chosen yet, or the last attempt failed.
requires_confirmation	The method is chosen; confirm it.
requires_action	The customer has something to do: next_action says what.
processing	The customer acted and the outcome is not known yet.
succeeded	The payment succeeded. Final.
canceled	Canceled before it was paid. Final.

Without a method, a new intent lists payment_method_types: the methods your account can take this payment with now. Your customer pays it in one of three ways:

• Hosted checkout: send them to our checkout page, at next_action.redirect_to_url.url. This is the default.
• Embedded checkout: create the intent with checkout_mode embedded, and show the same checkout inside your own page, inline or in a modal. See Embedded checkout.
• Your own page: show them the methods yourself and confirm with the one they choose in payment_method_data[type], then show them what next_action says. See API-only integration.

With a method, the intent is requires_confirmation and its method is fixed from the start.

What next_action says

While an intent is requires_action, next_action.type says what the customer is to do:

type	What the customer does
redirect_to_url	Visits a page: our hosted checkout page, or our card page, where a card is typed.
mount_embedded_checkout	Pays inside embedded checkout on your page.
qrph_display_qr_code	Scans a QR Ph code with any bank or e-wallet app.
cash_display_reference	Pays a reference in cash at a collection location.

Build your integration to ignore a type it does not know, as for any field.

A failed attempt does not end the intent

A declined card, a failed payment, or a customer who did not pay in time or turned back returns the intent to requires_payment_method, with last_payment_error saying why, and sends payment_intent.payment_failed. Confirm it again to start a new attempt, with the same method or, as payment_method_types lists, another: a new method is priced when it is chosen. An outcome we cannot know yet is processing, never a failure.

Cancelling

Cancel an intent that has not been paid: from requires_payment_method, requires_confirmation or requires_action. It cannot be cancelled once it is processing or succeeded. Cancelling an intent also cancels any cash reference it was given, so cash can no longer be paid against it.