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’sterms, 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 themandateId of a mandate and no captureMethod. Natural charges the card at once. The intent has no checkout link.
completed: the card was charged.cardPayment.succeededandpaymentIntent.completedfire.declined: the charge failed, and nothing is charged.cardPayment.failedfires. To charge again, create a new intent.processing: the issuer hasn’t answered yet. Get the intent later to seecompletedordeclined.
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 withcaptureMethod: "manual" and the mandateId of a mandate:
authorized: the issuer approved the hold. Capture it beforecaptureBefore.declined: the issuer declined the hold. Nothing is charged.processing: the issuer hasn’t answered yet.
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.