Pipecat

Add card-on-file payments to a Pipecat voice pipeline 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 in your pipeline; 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 pipeline.

Prerequisites

A running Pipecat pipeline with telephony (a Twilio/Telnyx/Plivo/Exotel WebSocket serializer, or Daily PSTN/SIP dial-in).
The telephony account that owns the inbound call leg, and a Ringup API key.

Set up

Using Dashboard
Using Tools

Your pipeline 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 pipeline; 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 pipeline 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

Register a function on your LLM (FunctionSchema) that the model calls once the order is confirmed, and in its 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.

async def create_checkout(params: FunctionCallParams):
    r = await http.post(
        "https://api.ringup.dev/v1/create_checkout",
        headers={"Authorization": f"Bearer {RINGUP_KEY}"},
        json={
            "merchant_id": merchant_id,
            "caller_phone": caller_number,
            "order_id": params.arguments.get("order_id"),          # the total is read from it
            "platform_call_id": call_id,                           # optional
            "return_to": "sip:your-bridge@your-telephony",         # optional: bring the caller back
            "success_message": "You are all set, your order will be ready shortly.",  # optional
        },
    )
    await params.result_callback(r.json())

{
  "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 transport

Have the agent speak one short bridge line (“One moment, connecting you to secure payment”), then transfer the caller on your telephony. On a Twilio transport, 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>

On Daily PSTN/SIP, use the equivalent SIP transfer to the same URI.

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 pipeline and call Ringup’s tools straight from your function 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, available 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" }'

caller = requests.post(
    "https://api.ringup.dev/v1/identify",
    headers={"Authorization": "Bearer <YOUR_RINGUP_KEY>"},
    json={"caller_phone": caller_number},
).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"
  }'

checkout = requests.post(
    "https://api.ringup.dev/v1/create_checkout",
    headers={"Authorization": "Bearer <YOUR_RINGUP_KEY>"},
    json={
        "merchant_id": merchant_id,
        "caller_phone": caller_number,
        "order_id": order_id,  # or amount_cents, when there is no order
    },
).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" }'

res = requests.post(
    "https://api.ringup.dev/v1/charge",
    headers={"Authorization": "Bearer <YOUR_RINGUP_KEY>"},
    json={
        "checkout_session_id": checkout["checkout_session_id"],
        "instrument_id": card["instrument_id"],  # the card the caller agreed to
    },
)
# a decline is a 402: speak res.json()["error"]["agent_message"]
charge = 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" }'

link = requests.post(
    "https://api.ringup.dev/v1/send_link",
    headers={"Authorization": "Bearer <YOUR_RINGUP_KEY>"},
    json={"checkout_session_id": checkout["checkout_session_id"]},
).json()
# link["sent"] is False on 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

Prerequisites

Set up

Next steps

Testing

Webhooks

​Prerequisites

​Set up

​Next steps

Testing

Webhooks

Prerequisites

Set up

Next steps