payment_intent.requires_action

POST

A payment intent waits for the customer: next_action says what they are to do. Sent when an intent is confirmed, and when one is created without a method to wait at our hosted checkout page or in embedded checkout. For that one, next_action is null: read the intent for its hosted checkout link, or its embedded checkout client token.

Authorizations

• AccessToken

Request Body

Media typeapplication/json

object

id

required

Deduplicate on this; the same event may arrive more than once.

string

object

required

string

Allowed value: event

type

required

string

created

required

A Unix timestamp.

integer

api_version

required

string

Allowed value: v1

livemode

required

boolean

tenant_id

string

merchant_id

string | null

data

required

object

object

The object as the API shows it, as of this event.

object

data

required

object

object

object

id

required

string

object

required

string

Allowed value: payment_intent

amount

required

In the currency’s minor unit.

integer

amount_received

required

The amount paid: amount once succeeded, and 0 until then.

integer

currency

required

A three-letter ISO 4217 code, in lower case.

string

/^[a-z]{3}$/

payment_method_types

required

The chosen method, such as [qrph], once there is one. Until then, the methods that can take this payment now: confirm with one. In an event for an intent with no method, the methods you allowed at creation, or null if you allowed any.

Array<string> | null

channel

required

Where the payment is taken: ecommerce for every intent your server creates. Payments taken on terminals will say pos (Pending).

string

status

required

string

Allowed values: requires_payment_method requires_confirmation requires_action processing succeeded canceled

next_action

required

One of:

object

object

type

required

string

Allowed value: qrph_display_qr_code

qrph_display_qr_code

required

object

data

required

The QR payload. Render it as a QR code for the customer to scan with their banking app.

string

expires_at

required

When the code stops being payable, as a Unix timestamp.

integer | null

object

object

type

required

string

Allowed value: cash_display_reference

cash_display_reference

required

object

reference

required

The payment reference, unique to this attempt. Give it to the customer to pay at a cash collection location.

string

amount

required

The exact amount to pay, in the currency’s minor unit.

integer

currency

required

A three-letter ISO 4217 code, in lower case.

string

/^[a-z]{3}$/

expires_at

required

When the reference stops being payable, as a Unix timestamp. After it the attempt fails as expired.

integer

instructions

required

Words to show the customer. May be reworded, so never branch on it.

string

object

object

type

required

string

Allowed value: redirect_to_url

redirect_to_url

required

object

url

required

The payment page: a card’s, or our hosted checkout page for an intent created without a method. Send the customer there.

string format: uri

return_url

Where the customer comes back to, or null when you gave none: your return_url, or our hosted checkout page when the customer chose card there, which then sends them on to yours. For the hosted checkout page itself, the return_url you gave on create.

string | null format: uri

object

An intent created with checkout_mode embedded, waiting for the customer in embedded checkout on your page. See Embedded checkout.

object

type

required

string

Allowed value: mount_embedded_checkout

mount_embedded_checkout

required

object

client_token

required

What your page mounts embedded checkout with, beside your publishable key, from one of your registered origins. The same on every read while it is here. It opens this one payment’s checkout: give it only to the customer paying.

string

/^ct_/

expires_at

required

When the checkout session ends, as a Unix timestamp. After it, the client token opens nothing.

integer

null

null

last_payment_error

required

One of:

object

object

code

required

card_declined: the card was declined. expired_card: the card has expired (test mode only today). payment_intent_authentication_failure: the customer did not complete the card’s authentication. payment_intent_payment_attempt_failed: the attempt failed, or the customer left without paying. payment_intent_payment_attempt_expired: the customer did not pay in time.

string

Allowed values: card_declined expired_card payment_intent_authentication_failure payment_intent_payment_attempt_failed payment_intent_payment_attempt_expired

decline_code

Why the card was declined, when the decline names a reason. Test mode only today: it appears when you simulate a decline with a decline_reason (see Simulate a payment’s outcome), and a live decline does not carry it yet, so never depend on it there.

string

Allowed values: insufficient_funds do_not_honor expired_card

message

required

Words you can show the customer. May be reworded, so never branch on it.

string

null

null

cancellation_reason

required

The reason given when it was canceled, if any.

string | null

Allowed values: requested_by_customer duplicate fraudulent abandoned

canceled_at

required

When it was canceled, as a Unix timestamp.

integer | null

description

required

string | null

metadata

required

The metadata you gave it. {} if none.

object

key

additional properties

string

livemode

required

boolean

created

required

When it was created, as a Unix timestamp.

integer

Responses

200

Received. Answer with any 2xx within 10 seconds.