OpenAI Realtime

Add card-on-file payments to an OpenAI Realtime agent two ways. In your agent keeps the caller on your bridge; your code calls Ringup’s tools to recognize the caller and charge the saved card, with no transfer. Recommended on Realtime: it needs nothing from the carrier leg, so it sidesteps the SIP REFER interop that hosted transfer depends on. Hosted transfers the call to a Ringup payment line at payment time. Either way a recognized caller never reads a card aloud, so no card data touches your bridge.

Prerequisites

A running OpenAI Realtime agent reachable over the phone (Twilio media streams, the SIP connector, or your own SIP trunk).
The telephony account that owns the inbound call leg, and a Ringup API key.

Set up

Using Tools
Using Dashboard

Keep the caller on your bridge and call Ringup’s tools straight from your handler with plain HTTP. No transfer, no payment line, and no dependence on the carrier leg honoring a SIP REFER.

Recognize the caller at the greeting

Call identify at the greeting, not at payment. Pass caller_phone, which your telephony resolved when the call connected. For a returning caller it returns their name, so your agent greets them by name and skips questions it can already answer. An unknown caller comes back known: false, an ordinary first call. See Recognize at the start of the call.

curl -X POST https://api.ringup.dev/v1/identify \
  -H "Authorization: Bearer <YOUR_RINGUP_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "caller_phone": "+14155550142" }'

const caller = await fetch("https://api.ringup.dev/v1/identify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_RINGUP_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ caller_phone: callerNumber }),
}).then((r) => r.json());
// caller.known tells you whether to greet by caller.consumer.first_name

Open a Checkout Session when the order is confirmed

POST to create_checkout with the merchant and the caller. Ringup resolves the total (from the merchant’s order when you pass order_id), applies the merchant’s payment policy, and returns cards: the caller’s cards chargeable at this merchant. On payment_required: "none" say nothing about payment and finish the call.

curl -X POST https://api.ringup.dev/v1/create_checkout \
  -H "Authorization: Bearer <YOUR_RINGUP_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mch_1fd0e6c96e6dcd7681f2",
    "caller_phone": "+14155550142",
    "order_id": "ord_7f21"
  }'

const checkout = await fetch("https://api.ringup.dev/v1/create_checkout", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_RINGUP_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_id: merchantId,
    caller_phone: callerNumber,
    order_id: orderId,           // or amount_cents, when there is no order
  }),
}).then((r) => r.json());
// checkout.payment_required === "none" means say nothing about payment

Charge the card the caller picked

Read one card from cards back by brand and last four with the amount. After the caller agrees, POST to charge with the session and that card’s instrument_id. Ringup charges it off-session on the merchant’s own processor. A decline is a 402 in the standard error envelope, carrying the sentence your agent can speak.

curl -X POST https://api.ringup.dev/v1/charge \
  -H "Authorization: Bearer <YOUR_RINGUP_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "checkout_session_id": "cs_test_x9f2", "instrument_id": "ins_4b7e" }'

const res = await fetch("https://api.ringup.dev/v1/charge", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_RINGUP_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    checkout_session_id: checkout.checkout_session_id,
    instrument_id: card.instrument_id,   // the card the caller agreed to
  }),
});
if (!res.ok) { /* a decline is a 402: speak error.agent_message */ }
const charge = await res.json();
// read charge.order_id back only when charge.status === "succeeded"

Text a link when there is no card to offer

When cards is empty (or the charge declined), POST to send_link. The session is the only input, and Ringup texts a secure pay link. Check sent: false means a duplicate send returned the same link without texting again. See Send Link.

curl -X POST https://api.ringup.dev/v1/send_link \
  -H "Authorization: Bearer <YOUR_RINGUP_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "checkout_session_id": "cs_test_x9f2" }'

const link = await fetch("https://api.ringup.dev/v1/send_link", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_RINGUP_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ checkout_session_id: checkout.checkout_session_id }),
}).then((r) => r.json());
// link.sent === false means a duplicate send: no new text went out, so do not promise one

In the Ringup dashboard, under Webhooks, add your HTTPS endpoint and copy the signing secret. Your code verifies the signature and handles checkout.succeeded. See Webhooks.

Test it, then go live

Use your rk_test_ key and call your agent from your own phone. On your first call you are texted a link and pay with the test card 4111 1111 1111 1111 (any future expiry, any CVC); on the next call you are recognized and pay on the saved Visa ending 1111. Expect the confirmation read back and a test-mode checkout.succeeded. Swap in your rk_live_ key to go live.

Your bridge creates a Checkout Session and transfers the live call to it, like redirecting to a hosted web checkout. Ringup takes payment on its own line and returns the caller if you ask it to.

The caller must arrive over a carrier leg that honors an inbound SIP REFER: an Elastic SIP Trunk does, a plain programmable-voice API leg does not. Point your OpenAI SIP origination at a trunk-grade number, or use the Using Tools tab, which never transfers.

The wiring is code in your bridge; only your account side (API keys, the webhook endpoint, go-live) lives in the dashboard.

Recognize the caller at the greeting

Call identify from your bridge at the greeting, not at payment (plain HTTP, like the checkout call below). For a returning caller it returns their name, so your agent greets them by name. Chargeable cards come later, from the Checkout Session. See Recognize at the start of the call.

Create a Checkout Session when the order is confirmed

Give the model a Realtime function that signals the order is ready to pay, and in your handler POST to Ringup with your API key. If payment_required is none, do not transfer: finish the call normally. Otherwise transfer to the returned transfer_to.

POST https://api.ringup.dev/v1/create_checkout
Authorization: Bearer <YOUR_RINGUP_KEY>
Content-Type: application/json

{
  "merchant_id": "mch_1fd0e6c96e6dcd7681f2",
  "caller_phone": "+14155550142",
  "order_id": "ord_7f21",                            // the merchant's order; the total is read from it
  "return_to": "sip:your-bridge@your-telephony",        // optional: transfer the caller back after payment
  "platform_call_id": "call_abc123",                 // optional: ties the payment to your call logs
  "success_message": "You are all set, your order will be ready shortly."  // optional (if no return_to)
}

{
  "checkout_session_id": "cs_test_x9f2",                  // the correlation token
  "payment_required": "required",                    // "required" | "optional" | "none"
  "amount_cents": 1900,                              // resolved from the order
  "currency": "USD",
  "amount_source": "order",                          // "order" | "request"
  "transfer_to": "sip:eyJrIjoiY3NfdGVzdF80NTNiNTQwMTI4NmQwZjgwIiwieCI6MTc4NDk1MjU3MTU5N30.vSkGB9zGRuR6fRhRHxmcTvYQZ5mi@transfer.ringup.dev",  // null unless payment is required
  "transfer_to_number": "+13235047170",              // dial this on platforms that transfer only to phone numbers
  "expires_at": "2026-07-21T18:35:12Z",
  "cards": [],                                       // saved cards chargeable at this merchant
  "default_card_id": null,
  "metadata": null
}

Transfer on your bridge

Have the agent speak one short bridge line (“One moment, connecting you to secure payment”), then transfer the caller on your telephony. On Twilio, redirect the call to TwiML that dials the Ringup SIP URI, carrying the checkout_session_id:

<Response>
  <Dial>
    <Sip>sip:eyJrIjoiY3NfdGVzdF80NTNiNTQwMTI4NmQwZjgwIiwieCI6MTc4NDk1MjU3MTU5N30.vSkGB9zGRuR6fRhRHxmcTvYQZ5mi@transfer.ringup.dev</Sip>
  </Dial>
</Response>

If your call arrives over the SIP connector, a SIP REFER to the same URI works too.

In the Ringup dashboard, under Webhooks, add your HTTPS endpoint and copy the signing secret. Your code verifies the signature and handles checkout.succeeded. See Webhooks.

Test it, then go live

Use your rk_test_ key, call your agent from your own phone, and order: on your first call you are texted a link and pay with the test card 4111 1111 1111 1111 (any future expiry, any CVC); on the next call the payment line recognizes you and charges the saved Visa ending 1111. Expect the payment line to read a confirmation code and a test-mode checkout.succeeded at your endpoint. Swap in your rk_live_ key to go live.

Before you go live: add the Connect button to your dashboard. Wiring the payment tools into your agent does not, by itself, let any charge settle. Each merchant must first connect their own payment processor, from a button you embed on your merchant-facing dashboard:

<script src="https://ringup.dev/connect/button.js"
        data-ringup-key="pk_test_..."></script>

That is your publishable key, not your secret one. Ship it alongside this integration so a merchant can connect the moment they are ready; until they do, the payment layer stays inaudible on their calls, so going live early is safe. Button options and the connect flow: Payment providers.

Get started

Concepts

Developer integrations

Merchant integrations

OpenAI Realtime

Prerequisites

Set up

Next steps

Testing

Webhooks

​Prerequisites

​Set up

​Next steps

Testing

Webhooks

Prerequisites

Set up

Next steps