A slot that needs no card confirms without pausing for payment. Every slot Ophelia returns says in
terms.card_required whether it needs one.
What you need
- Production client credentials for your company, exchanged for an access token (Create an access token). Agentcard refuses an API key here, and sandbox cards cannot pay a live venue.
- A user connected to your company with a card in the Vault (Adding a card, Check for stored cards).
- An Ophelia v1 key, live or test, from the Ophelia dashboard.
- A way to reach the diner within minutes, for the approval link and for the venue’s SMS code.
Create the booking
Send"payment_collection": "agentcard_external" and no card fields. The billing fields in metadata are what the venue’s processor checks against the card, so send the user’s real postal code and country.
status every few seconds with GET /v1/bookings/{id}. Within about a minute an OpenTable booking reads requires_action with next_action.type set to payment_authorization:
agentcard_request is the body of Create a checkout authorization without the user. The request inside it is the venue’s own card request with a placeholder card in the body; the user’s device swaps the real card in. expires_at is Ophelia’s deadline, 15 minutes from the pause.
Branch on next_action.type every time you read the booking. A Resy booking asks for the venue’s SMS code first: next_action.type reads otp, and you post the code the diner received as {"otp_code": "123456"} to /continue. Ophelia’s guide covers that step.
Create the checkout authorization
Copyagentcard_request unchanged, add user, and post it with your access token.
amount is null and the approval screen shows the venue’s name without a price. Tell the user what they approve: the venue keeps their card on file and charges it only under its no-show policy. Ophelia returns that policy in the slot’s terms, with the fee and the cancellation cutoff.
Send the user the approval link
SendapprovalUrl to the user wherever you already talk to them: a chat thread, an iMessage, an email, your app (Choose a platform). The user opens the link, sees Gary Danko, and confirms with Face ID, Touch ID, fingerprint, or their master password. Their device sends the real card to the venue’s processor, and Agentcard stores the processor’s answer on the authorization.
Hand the answer back to Ophelia
Read the authorization everyinterval seconds until status leaves awaiting_approval.
approved, the authorization carries response: the processor’s answer, with the card already turned into a token.
response object to Ophelia as psp_response, and nothing else from the authorization.
202 means Ophelia is still working: read GET /v1/bookings/{id} until the booking reads confirmed or failed. A requires_action means another step; branch on next_action.type again. A malformed psp_response gets 400 and the booking stays paused, so fix the body and post it again before expires_at.
Abandon the payment
When the user declines, or the authorization readsdeclined or expired, tell Ophelia to stop.
error_code set to payment_declined, and the venue holds nothing.
Stop at Ophelia’s deadline, not Agentcard’s. Both windows last 15 minutes, but Agentcard’s starts when you create the authorization, after Ophelia’s pause, so it outlives Ophelia’s. Leave 30 seconds for your own /continue call. When Ophelia’s expires_at passes, cancel the authorization so the user cannot approve a payment that can no longer complete (Cancel a checkout authorization), and read what the cancel returns before you do anything else.
200withcancelled: true: the user’s approval link stops working and no card was sent. Start a new booking.409withoutcome_unknown: the user’s device has already started sending the card, so the attempt is still running. Read the authorization everyintervalseconds until it leavesawaiting_approval. When it readsapproved, the card reached the venue’s processor, so check with the venue before you book again.
psp_response that arrives after expires_at gets 400, and the booking fails with payment_outcome_unknown. The card can still have reached the venue, so check with the venue before you book again.
When the booking fails
A failed booking readsstatus: "failed" with an error_code and an error_message. A 400 from /continue carries only an error message, so read the booking to learn which case happened.
Two refusals come at create, before a booking exists.
409 vault_unavailable means the venue cannot be paid through Agentcard, so offer another venue or time. 503 agentcard_disabled means Agentcard payments are off for your Ophelia account, so contact Ophelia.
On the Agentcard side, an authorization that reads declined or expired sent no card. Abandon the booking with psp_abort as shown above.
Know what Agentcard read back
The venue’s request stores the card for later and charges nothing at approval. The authorization’ssettlement therefore reads unknown with reason no_processor_reference and final: true: Agentcard holds no reference at the processor to read back, and the booking’s confirmation_code is the proof that the hold is in place. The checkout_authorization.approved event fires when the user approves, so you can wait on it instead of reading the authorization every few seconds. The event does not carry response, so read the authorization once when it arrives and post its response to Ophelia as psp_response. A later cancellation of the booking leaves the authorization as it is; nothing remains to cancel once the user has approved.
Test it
Ophelia has no sandbox for card holds, and Agentcard’s sandbox cards cannot pay a live venue. Test with production credentials, a real card in the Vault, and a slot a few days out at a venue whose availability readscard_required: true. Cancel the booking with POST /v1/bookings/{id}/cancel as soon as it confirms. OpenTable cancels at the venue. A confirmed Resy booking stays confirmed, so cancel it in the diner’s Resy account.
Ophelia’s own guide, AgentCard payments, covers the booking side in full: webhooks, timing, and every error code.