Skip to main content
Setup intents are part of Accept, which is in early access and subject to change. To request Accept access, contact hi@natural.com.
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. When the payer finishes, the setup intent carries a mandate (mdt_*) that you charge or hold under while the payer is away.

​
Create a setup intent

Create a setup intent with the mandate’s terms in terms:
  • description: what you charge for, shown to the payer. For example, “Damage deposit for your stay”.
  • amountType and amount: fixed charges exactly amount; variable charges up to amount, in cents.
  • usage: singleUse allows one paid charge. multiUse allows any number of charges, each within amount, until validUntil. Use multiUse for a deposit: a singleUse mandate refuses a new hold while one is open.
  • validUntil: when the mandate ends.
expiresAt on the setup intent itself is when the link closes. It defaults to validUntil and can’t be later. Send the payer to setupUrl, or pass clientSecret to natural.js to show the form on your page. The payer verifies their phone, types a card and accepts the terms. Natural verifies the card with a zero-amount check. The setup intent doesn’t return the terms. Once it completes, get the mandate to read them.

​
Statuses

  • open: waiting for the payer, and again after a card fails.
  • processing: Natural is verifying the card.
  • completed: the card is saved and the mandate is active. relationships.mandate links the mandate.
  • declined: five cards failed on the link. It saves no more.
  • canceled: you canceled it.
  • expired: expiresAt passed while it was open.
Cancel a setup intent only while it’s open. Canceling never ends a mandate it already created; revoke the mandate for that.

​
Events

mandate.created fires when the payer saves a card.