LiveKit Agents

Add card-on-file payments to a LiveKit agent two ways. Hosted transfers the SIP participant to a Ringup payment line at payment time; Ringup runs the whole payment. In your agent keeps the caller in your agent; your code calls Ringup’s tools to recognize the caller and charge the saved card, with no transfer. Either way a recognized caller never reads a card aloud, so no card data touches your agent.

Prerequisites

A running LiveKit agent with SIP inbound configured (the caller arrives as a SIP participant).
Your LiveKit server credentials, and a Ringup API key.

Set up

Using Dashboard
Using Tools

Your agent creates a Checkout Session and transfers the SIP participant 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 wiring is code in your agent; only your account side (API keys, the webhook endpoint, go-live) lives in the dashboard.

Recognize the caller at the start

Call identify from your agent code at the greeting, not at payment (plain HTTP, like the checkout call below). The caller’s number arrives the instant the call connects; for a returning caller identify 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

POST to create_checkout with your Ringup 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-agent@your-sip-host",          // 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 the SIP participant

Speak one bridge line, then transfer the caller’s SIP participant to transfer_to, attaching the checkout_session_id as a REFER header as a backstop:

# after saying: "One moment, connecting you to secure payment."
await livekit_api.sip.transfer_sip_participant(
    room_name=room,
    participant_identity=caller_identity,
    transfer_to=checkout["transfer_to"],                 # sip:eyJrIjoiY3NfdGVzdF80NTNiNTQwMTI4NmQwZjgwIiwieCI6MTc4NDk1MjU3MTU5N30.vSkGB9zGRuR6fRhRHxmcTvYQZ5mi@transfer.ringup.dev
    headers={"X-Session-Id": checkout["checkout_session_id"]},  # cs_test_x9f2
    play_dialtone=False,                                 # the bridge line covers the gap
)

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.

Keep the caller in your agent and call Ringup’s tools straight from your agent code with plain HTTP. No transfer, no payment line.

Recognize the caller at the greeting

Call identify at the greeting, not at payment. Pass caller_phone, which LiveKit gives you the instant the SIP participant joins. 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.

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

LiveKit Agents

Prerequisites

Set up

Next steps

Testing

Webhooks

​Prerequisites

​Set up

​Next steps

Testing

Webhooks

Prerequisites

Set up

Next steps