Skip to main content

Save a card with a setup intent

A saved card is charged under a mandate. To get one, create a setup intent with the mandate’s terms, then send the payer to setupUrl or pass clientSecret to natural.js. It takes only a Visa or Mastercard the payer types in. Once it completes, get the mandate to read the terms: the setup intent doesn’t return them.

Charge a saved card now

To charge a payer’s saved card while they’re away, create a payment intent with the mandateId of a mandate and no captureMethod. Natural charges the card at once. The intent has no checkout link.
The intent comes back in one of three statuses:
  • completed: the card was charged. cardPayment.succeeded and paymentIntent.completed fire.
  • declined: the charge failed, and nothing is charged. cardPayment.failed fires. To charge again, create a new intent.
  • processing: the issuer hasn’t answered yet. Get the intent later to see completed or declined.
cardPayment.created doesn’t fire for these charges.

Holds

A hold reserves an amount on the payer’s card and charges it only if you capture it. For example, hold a $500 damage deposit before a guest checks in, and charge it only if there’s damage. To place a hold, create a payment intent with captureMethod: "manual" and the mandateId of a mandate:
The intent comes back in one of three statuses:
  • authorized: the issuer approved the hold. Capture it before captureBefore.
  • declined: the issuer declined the hold. Nothing is charged.
  • processing: the issuer hasn’t answered yet.
Listen for paymentIntent.authorized. It fires once when the issuer approves the hold, even if the intent already came back authorized. A decline fires cardPayment.failed instead. Capture the intent to charge the full amount. For a damage deposit with no damage, cancel the intent to release the hold. With damage, cancel the intent, then charge the saved card for the damage with the same mandateId. For example, for 12000 of damage on a 50000 deposit, cancel the hold and charge 12000. This needs a variable agreement (terms.amountType): a fixed one charges exactly amount. The card is charged when the intent reads completed, and paymentIntent.completed fires. The intent’s capturedAmount shows what was charged. While the charge is in progress, capture returns the intent still authorized, or 503 paymentIntent.capturePending. Get the intent later. If it’s still authorized, capture again with a new Idempotency-Key. That can’t charge twice: while a capture is in progress, it’s refused with 409 paymentIntent.notCapturable. Revoking the mandate doesn’t release an open hold. Cancel the intent to release the hold; paymentIntent.canceled fires. A hold you don’t capture before captureBefore reads expired. Natural doesn’t charge the card, and no event fires. For other capture and cancel errors, see Payment Intents errors.