Skip to main content
Ophelia books restaurant tables on OpenTable and Resy through one API. When a venue needs a card to hold the table, Ophelia pauses the booking and hands you the venue’s card request. You post that request to Agentcard, the user approves it with their passkey, and their device puts their real card into the request. You hand the processor’s answer back to Ophelia, and the venue holds the table. The card number never reaches you or Ophelia. 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

  1. 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.
  2. A user connected to your company with a card in the Vault (Adding a card, Check for stored cards).
  3. An Ophelia v1 key, live or test, from the Ophelia dashboard.
  4. A way to reach the diner within minutes, for the approval link and for the venue’s SMS code.
Every booking is a real reservation, on test keys too. Cancel the ones you make while testing.

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.
Ophelia answers with the booking. Read 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

Copy agentcard_request unchanged, add user, and post it with your access token.
A hold carries no amount, so 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 approvalUrl 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 every interval seconds until status leaves awaiting_approval.
On approved, the authorization carries response: the processor’s answer, with the card already turned into a token.
Post the response object to Ophelia as psp_response, and nothing else from the authorization.
Ophelia finishes the venue’s card step and answers with the booking. On OpenTable the answer took eight seconds in a live run:
A 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 reads declined or expired, tell Ophelia to stop.
The booking fails with 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.
  • 200 with cancelled: true: the user’s approval link stops working and no card was sent. Start a new booking.
  • 409 with outcome_unknown: the user’s device has already started sending the card, so the attempt is still running. Read the authorization every interval seconds until it leaves awaiting_approval. When it reads approved, the card reached the venue’s processor, so check with the venue before you book again.
A 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 reads status: "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’s settlement 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 reads card_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.