Taking card payments for a customer instead of your own business? Pass their party ID as
customerPartyId on every call below. See Accept payments.Amounts are integer US cents:
50000 is $500.00.Create the intent
Create the intent withPOST /payment-intents. To change it while it’s open, update the intent; the pay page shows the new total before the payer pays. The checkout of a subscription can’t be updated.
When an agent (
agt_*) creates, cancels, fulfills, or declines a payment, payment request,
transfer, payment intent, refund, or voice session, it authenticates with its own credential (an
agent key or an agent-scoped OAuth grant) and names
the run with the X-Instance-ID header. Without it the call returns 400 missingInstanceId.
Reads don’t need it.data.attributes.payUrl. You can also include line items and tax. Line totals must add up to the payment intent amount.
Hand the payer the link
SendpayUrl to the payer. Treat the link as private. They can enter a card, use Apple Pay or Google Pay where available, or use a saved card after entering a code sent to their phone. Natural handles checkout, 3-D Secure when its risk check on a typed card asks for it or a saved card is retried after a failed payment, and the receipt.
To change the amount, line items, or other details, update the intent while it is open. A payer who already has the checkout open must review the new terms before paying. The checkout of a subscription can’t be updated.
Follow the payment
Read the intent withGET /payment-intents/{paymentIntentId}. Check its status to see whether it was paid.
completed. Its cardPayment relationship identifies the successful payment. Funds become available after settlement.
Subscribe to paymentIntent.completed, cardPayment.succeeded, and cardPayment.failed webhooks for updates. See Card payments for failed attempts.
Reconcile
List payment intents to review recent activity. Filter by status or creation date. Usecursor for the next page and customerPartyId for a customer’s intents.
Cancel an intent
Cancel an open intent withPOST /payment-intents/{paymentIntentId}/cancel. The checkout link stops working. For cURL, send data.attributes even when empty.
An intent with a payment in progress cannot be canceled, and neither can one that already
completed. Refund a completed payment instead: see Refund a card
payment.