Deepgram Voice Agent

Add card-on-file payments to a Deepgram Voice Agent two ways. Hosted transfers the call to a Ringup payment line at payment time; Ringup runs the whole payment. 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. Either way a recognized caller never reads a card aloud, so no card data touches your bridge.

Prerequisites

A running Deepgram Voice Agent behind your own audio bridge (Twilio media streams or similar).
Your bridge’s telephony account (the number the call comes in on), and a Ringup API key.

Set up

Using Dashboard
Using Tools

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 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). 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

When the agent signals the order is confirmed (for example via a Deepgram function call your bridge handles), 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-bridge@your-twilio-number",    // 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 your agent speak one bridge line (an InjectAgentMessage such as “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>

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 on your bridge and call Ringup’s tools straight from your handlers 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 your bridge has the instant the call connects. 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

Deepgram Voice Agent

Prerequisites

Set up

Next steps

Testing

Webhooks

​Prerequisites

​Set up

​Next steps

Testing

Webhooks

Prerequisites

Set up

Next steps