A setup intent is a link where a payer saves a card and agrees to let you charge it later. Nothing is charged when they save it. To learn more, see Charge a saved card.
The object is everything inside data. The field names below are relative to it: attributes.status is data.attributes.status in the response.
Fields
string
required
Setup intent ID (set_*).
string
required
Resource type. Always setupIntent.
object
required
The setup intent’s details.
Hide attributes
string
required
open until the guest saves a card, and again after a failed verification. completed once the card is saved and the agreement is active. canceled when you cancel it. declined once five cards failed on the link; it saves no more and the link is closed. expired once expiresAt passes while it’s open. One of: open, completed, canceled, declined, expired. See Statuses.
string | null
required
Hosted page where the guest saves a card, while the setup intent is open. Null after that.
string | null
required
Pass to natural.js in the browser to show the save card form on your page. Available whenever setupUrl is. Treat it like a password: send it only to the guest’s browser.
object | null
required
Why the latest card failed, while the setup intent is open for another try or declined. Null otherwise.
Hide lastFailure
string | null
required
Failure code, when known. New codes may be added.
string | null
required
Explanation of the failure.
string | null
required
Recommended payer action, when known. One of: doNotRetry, tryAgainLater, confirmCardData.
string | null
required
RFC 3339 timestamp after which the guest can no longer save a card. No later than the agreement’s validUntil.
string | null
required
RFC 3339 timestamp when the setup intent was canceled.
string
required
RFC 3339 timestamp when the setup intent was created.
string
required
RFC 3339 timestamp when the setup intent record last changed. expired is read live.
object
required
Related resources, each by type and ID.
Hide relationships
object
required
The card agreement the saved card is charged under. Read its terms with GET /mandates/{mandateId}. Null until completed.
Hide mandate
object | null
required
Related resource identifier.
Hide data
string
required
Resource type. Always mandate.
string
required
Mandate ID (mdt_*).
Statuses
Status
Meaning
Can become
open
Waiting for the payer, and again after a card fails.
completed, declined, canceled, expired
completed
The card is saved and the mandate is active. relationships.mandate links the mandate.
Final
canceled
You canceled it.
Final
declined
Five cards failed on the link, because the bank declined them or they aren’t a Visa or Mastercard. It saves no more, and no event fires.
Final
expired
expiresAt passed while it was open. You can still cancel it. No event fires.
canceled
Permissions
Create and cancel need paymentIntents.create. Get needs paymentIntents.read.
Events
setupIntent.completed: Early access (setup intents). A payer saved a card. relationships.mandate links the new mandate, and mandate.created fires for it.
setupIntent.canceled: Early access (setup intents). You canceled an open setup intent. Its link no longer saves a card.