Skip to main content
Ringup has two integration modes, and the endpoints below power both. In your agent you keep the caller in your own agent: call identify at the greeting, create_checkout when the order is ready, then charge the card the caller picked, or send_link when the session offers none. Nothing transfers. Hosted opens the same Checkout Session and transfers the call to Ringup’s payment line, which runs the payment and posts you a webhook. Pick the mode that fits your agent; the same identity and the same off-session charge sit underneath both.
Stability. The request and response shapes on this page are stable. The API is versioned in the base path (/v1): within a version, changes are additive (new optional fields only), and any breaking change ships under a new version. Pin the version and upgrade on your own schedule. See the Changelog for what has shipped.

​
Base URL

​
Authentication

Every request authenticates with your Ringup API key as a Bearer token:
Create a key in the dashboard under API Keys. Test keys start with rk_test_ and live keys with rk_live_; the key decides which mode the request runs in. See Authentication for test versus live keys and how to keep the key safe.

​
The payment lifecycle

​
Identity travels in the body

The caller and the merchant are ordinary request fields: caller_phone on identify and create_checkout, and merchant_id on create_checkout. One value in one place, so no consumer has to reason about which of two copies wins. Fill all three in the code that assembles the request, from the platform’s call metadata. A value the model composes can be mistyped, hallucinated, or prompt-injected, and these three decide whose cards are offered and whose account the money reaches. See Caller Identity and Merchant Identity.
Web and dashboard test calls carry no real caller ID, so the caller-ID template resolves to nothing. Pin a test caller explicitly for those; real inbound phone calls resolve everything natively.

​
Idempotency

Charges are deduplicated server-side per Checkout Session. A platform retry, a model retry, or a duplicated tool call returns the original charge with replay: true instead of charging twice. This is a server guarantee, not a client convention.

​
Webhooks

Payment outcomes also arrive out of band as signed events: checkout.succeeded when a session is paid, checkout.failed on a decline or an expiry. Register your endpoint with POST /v1/webhook_endpoints; the response returns the signing secret once. See Webhooks.

​
Test mode

Your rk_test_ key answers the same endpoints at the same base URL. Create test merchants in the dashboard under Merchants; in test mode each is automatically backed by Ringup’s test processor account, with no merchant signup or OAuth. Every caller starts unknown: pay once on the texted pay link with the test card 4111 1111 1111 1111, and the caller is recognized with a saved Visa ending 1111 on every call after. See Testing.

​
Next steps

Errors

Transport errors versus payment outcomes, and the full catalog.

Webhooks

The event envelope, signatures, and idempotent handling.