charge runs one saved card against one open Checkout Session. The
caller is already recognized and the session already resolved the amount, so a charge takes two
values: which session, and which card the caller agreed to. Ringup charges it
and settles the money on the merchant’s own processor. The caller never reads a card aloud, so no
card data touches your agent.
The whole path
1
Recognize the caller at the greeting
identify with caller_phone tells you who is on the line.2
Open a session when the order is ready
create_checkout returns checkout_session_id, the resolved
amount_cents, and cards: the caller’s cards chargeable at this merchant.3
Offer a card and get a yes
Read one card back by brand and last four with the amount. Charge only after the caller agrees.
4
Charge the card they picked
Pass the session and that card’s
instrument_id.Response
The card is never defaulted
instrument_id is required. Ringup will not pick a card for you, even when the caller has exactly
one, and even though the session hands you default_card_id.
The caller agreed out loud to a specific card, and voice agents mishear. A dropped “use my
other one” plus an implicit default is how the wrong card gets charged with a spoken yes on record
for a different one. Naming the card in the request makes your agent’s choice explicit and
auditable.
The three statuses
pending is the one that needs care: it does not mean “nothing happened”. The outcome is
unknown, and the payment may already have gone through. So wait rather than charge again, and do
not tell the caller the payment failed.
Do not start a second payment for the same order. To retry, repeat the same charge call: it
carries the same idempotency key, so it cannot charge twice. Otherwise read the outcome from the
webhook or by reading the session back. We
resolve a pending charge for you by asking the processor what really happened.
Never tell the caller payment happened without a succeeded status.
A decline is a 402
A declined card is an error, not a result. It comes back as402 in the standard
error envelope, carrying the decline code and a sentence your agent can
speak, so an if (!response.ok) check catches it. It never arrives as a 200 with a sad status
inside.
The confirmation number is the order id
order_id is what the agent reads back. It is the merchant’s own number: the caller can quote
it and the merchant will find it. A Ringup id is a number only Ringup can look up, no use to a
caller standing at a counter.
Idempotent under retries
replay is true when this exact charge already happened and you are looking at the original. A
platform that auto-retries a slow tool call, a model that fires twice, a network retry: all return
the first charge instead of taking the money again. This is a server guarantee, not a client
convention.
Next steps
Webhooks
Your out-of-band source of truth for every charge.
Testing
The fixtures and cards to exercise a charge end to end.