Retell AI

Add card-on-file payments to a Retell agent two ways. Hosted hands the call to Ringup at payment time; Ringup runs the whole payment and you write no payment logic. In your agent keeps the caller in your agent the whole call: you call Ringup’s tools to recognize the caller and charge their saved card, and nothing transfers. Either way a recognized caller never reads a card aloud, so no card data touches your agent.

Prerequisites

A Retell agent you already run, with a phone number.
Your Retell API key, and a Ringup API key.

Set up

Using Dashboard
Using Tools

Ringup takes payment on a transfer. Best when you want the payment moment handled for you.

Connect Retell, once for your account

In the Ringup dashboard, open Voice integrations, then Connect Retell, and paste your Retell API key. Ringup uses it to list your agents and provision the payment objects, and never stores it. One connection covers every merchant you run.

Pick the agents that take payments

Select the agents that answer merchant calls. Ringup registers identify (called at the greeting), create_checkout, and the transfer_to_payment tool on each; paste the one prompt line the dashboard shows. No per-merchant step: the merchant resolves from the dialed number, and activates when it connects its processor.

Add your webhook endpoint

Under Webhooks, add your HTTPS endpoint and copy the signing secret. Ringup posts a signed checkout.succeeded there for every payment. See Webhooks.

Rehearse on the rehearsal number, then go live

The dashboard binds a test twin of your agent to a rehearsal number. Call it 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 you pay on the saved Visa ending 1111, no real charge. When it reads a confirmation code back, click Go live.

The hosted transfer needs a number Retell can move a call from: numbers bought through Retell and numbers imported over an elastic SIP trunk both work (for a trunk number, enable call transfer / SIP REFER at your provider). If your number cannot transfer, use the Using Tools tab, which never transfers.

Keep the caller in your agent and add four Retell custom functions pointed at Ringup, authed with your Ringup key. Retell interpolates {{user_number}} (the caller’s number, from the call) and {{merchant_id}} (a dynamic variable you set per merchant) before the model sees the tool, so the model composes neither identity.

Recognize the caller at the greeting

Register identify and call it at the greeting, not at payment. 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.

{
  "type": "custom",
  "name": "identify",
  "description": "Recognize the caller at the greeting. Returns their name if Ringup knows them.",
  "url": "https://api.ringup.dev/v1/identify",
  "method": "POST",
  "args_at_root": true,
  "headers": { "Authorization": "Bearer <YOUR_RINGUP_KEY>" },
  "parameters": {
    "caller_phone": { "type": "string", "description": "The caller's number. Always {{user_number}}." }
  }
}

Open a Checkout Session when the order is confirmed

Register create_checkout. It resolves the total, applies the merchant’s payment policy, and returns cards: the caller’s cards chargeable at this merchant. If payment_required is none, say nothing about payment and finish the call.

{
  "type": "custom",
  "name": "create_checkout",
  "description": "Open a payment session for the confirmed order. Returns whether payment is required and which saved cards can be used.",
  "url": "https://api.ringup.dev/v1/create_checkout",
  "method": "POST",
  "args_at_root": true,
  "headers": { "Authorization": "Bearer <YOUR_RINGUP_KEY>" },
  "parameters": {
    "merchant_id":  { "type": "string", "description": "The merchant. Always {{merchant_id}}." },
    "caller_phone": { "type": "string", "description": "The caller's number. Always {{user_number}}." },
    "order_id":     { "type": "string", "description": "The merchant's order id, if you have one. Ringup reads the total from it." },
    "amount_cents": { "type": "number", "description": "Order total in cents. Required only when there is no order_id." }
  }
}

Charge the card the caller picked

Register charge. Read one card from cards back by brand and last four with the amount, and call charge only after the caller agrees, with that card’s instrument_id.

{
  "type": "custom",
  "name": "charge",
  "description": "Charge the card the caller agreed to. Use the checkout_session_id and the instrument_id of the card you read back.",
  "url": "https://api.ringup.dev/v1/charge",
  "method": "POST",
  "args_at_root": true,
  "headers": { "Authorization": "Bearer <YOUR_RINGUP_KEY>" },
  "parameters": {
    "checkout_session_id": { "type": "string", "description": "From create_checkout" },
    "instrument_id":       { "type": "string", "description": "The card the caller agreed to, from the session's cards" }
  },
  "speak_during_execution": true,
  "execution_message_type": "static_text",
  "execution_message_description": "One moment while I put that through."
}

Text a link when there is no card to offer

Register send_link for a session whose cards is empty (or after a declined charge). Ringup texts a secure pay link and, when they pay, pushes the confirmation back into the live call (or sends it by SMS if the call has ended).

{
  "type": "custom",
  "name": "send_link",
  "description": "Text the caller a secure pay link for this session. Use when the session returned no cards.",
  "url": "https://api.ringup.dev/v1/send_link",
  "method": "POST",
  "args_at_root": true,
  "headers": { "Authorization": "Bearer <YOUR_RINGUP_KEY>" },
  "parameters": {
    "checkout_session_id": { "type": "string", "description": "From create_checkout" }
  }
}

Then add one line to your prompt: when the caller has confirmed the order, call create_checkout; if it returns cards, read one back and call charge after they agree, then read back the order id as the confirmation; if it returns none, call send_link and tell them to check their text to pay.

Add your webhook endpoint

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

Test it, then go live

Keep the functions’ url on https://api.ringup.dev/v1 and auth with 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 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

Prerequisites

Set up

Next steps

Testing

Webhooks

​Prerequisites

​Set up

​Next steps

Testing

Webhooks

Prerequisites

Set up

Next steps