Quickstart

Ringup adds identity and payments to a voice agent: a returning caller is recognized by phone number and pays with a saved card, settling on the merchant’s own processor, with no card number spoken. This quickstart runs that whole arc in test mode with your own phone number: no real money, and nothing faked.

Before you start

Get a test key

Sign in to the dashboard and create a key under API Keys. It starts with rk_test_ and works against the real API with no real money.

Add a test merchant

Under Merchants, add one. In test mode it is backed by Ringup’s test processor account automatically: no merchant signup, no OAuth. Copy its merchant_id (mch_…).

The arc

Recognize a caller

Ringup recognizes a caller from their phone number, which arrives the instant the call connects. Try it with your own number:

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

const res = await fetch("https://api.ringup.dev/v1/identify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RINGUP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ caller_phone: "+14155550142" }),
});
const caller = await res.json();

import os, requests

caller = requests.post(
    "https://api.ringup.dev/v1/identify",
    headers={"Authorization": f"Bearer {os.environ['RINGUP_API_KEY']}"},
    json={"caller_phone": "+14155550142"},
).json()

Response

{ "known": false, "consumer": null }

known: false is the ordinary first call, not an error. By the end of this page the same request returns your name. See Caller Identity.

Open a Checkout Session

When the order is ready to pay, create a Checkout Session for the caller at your test merchant. It resolves the amount, applies the merchant’s payment policy, and returns the caller’s chargeable cards:

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

const res = await fetch("https://api.ringup.dev/v1/create_checkout", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RINGUP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_id: "mch_1fd0e6c96e6dcd7681f2",
    caller_phone: "+14155550142",
    amount_cents: 2500,
  }),
});
const checkout = await res.json();

import os, requests

checkout = requests.post(
    "https://api.ringup.dev/v1/create_checkout",
    headers={"Authorization": f"Bearer {os.environ['RINGUP_API_KEY']}"},
    json={
        "merchant_id": "mch_1fd0e6c96e6dcd7681f2",
        "caller_phone": "+14155550142",
        "amount_cents": 2500,
    },
).json()

Response

{
  "checkout_session_id": "cs_test_453b5401286d0f80",
  "payment_required": "required",
  "amount_cents": 2500,
  "currency": "USD",
  "amount_source": "request",
  "transfer_to": "sip:eyJrIjoiY3NfdGVzdF80NTNiNTQwMTI4NmQwZjgwIiwieCI6MTc4NDk1MjU3MTU5N30.vSkGB9zGRuR6fRhRHxmcTvYQZ5mi@transfer.ringup.dev",
  "transfer_to_number": "+13235047170",
  "expires_at": "2026-07-25T05:35:12Z",
  "cards": [],
  "default_card_id": null,
  "metadata": null
}

cards is empty: this caller has nothing saved yet. That is exactly what send_link is for.

Save a card the way callers do

Text the pay link to the caller (you):

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

Your phone gets an SMS. Open it, enter a name and email, and pay with the test card 4111 1111 1111 1111, any future expiry, any CVC. The page saves the card and settles the payment against the test processor, and your server (once you register a webhook) receives checkout.succeeded.

Now you are a regular: charge the saved card

Run identify again with the same number:

Response

{
  "known": true,
  "consumer": { "id": "con_9c41f2ab8d6e37105b24", "first_name": "Alex", "last_name": "Rivera", "email": "alex@example.com" }
}

Open a fresh Checkout Session and cards now carries the Visa you just saved. After the caller agrees out loud, charge it:

curl -X POST https://api.ringup.dev/v1/charge \
  -H "Authorization: Bearer rk_test_5f2a8c1d9e4b7a3f6c0d" \
  -H "Content-Type: application/json" \
  -d '{ "checkout_session_id": "cs_test_9d2f7a3c1b8e6054", "instrument_id": "ins_7b3f6c0d9e4b5f2a8c1d" }'

Response

{
  "status": "succeeded",
  "amount_cents": 2500,
  "currency": "USD",
  "replay": false,
  "charge_id": "chg_8040cc0154671e7f2ea6",
  "checkout_session_id": "cs_test_9d2f7a3c1b8e6054",
  "processor_payment_id": "00467SVWM1EKC",
  "merchant_id": "mch_1fd0e6c96e6dcd7681f2",
  "order_id": null,
  "platform_call_id": null
}

That is the whole in-agent payment path: identify at the greeting, create_checkout when the order is ready, charge when the caller says yes. Only succeeded moved money. Open the session with the merchant’s order_id and it comes back on the charge, the number the agent reads out as the confirmation. See Charge.

Add it to your agent

You integrate one of two ways, and every platform guide documents both:

In your agent (API). Keep the caller in your own agent and add the endpoints you just called. Nothing transfers, and no card data touches your agent. The flexible path.
Hosted call transfer. Your agent transfers the live call to Ringup’s payment line (transfer_to, or transfer_to_number for platforms that only dial numbers), so you write no payment logic. The easiest path.

Pick your platform in Developer integrations: Vapi, Custom (REST), Retell, ElevenLabs, Deepgram, LiveKit, OpenAI Realtime, Pipecat, and Twilio ConversationRelay.

There is no per-merchant setup in your code: you pass merchant_id (resolved from the number the caller dialed) on every call, and each merchant activates for payments the moment its processor connects. Until then its sessions come back payment_required: "none" and the call runs normally.

Get started

Concepts

Developer integrations

Merchant integrations

Before you start

The arc

​Before you start

​The arc

Before you start

The arc