Authentication

Ringup has two kinds of credentials: a secret API key that authenticates every API request, and a publishable key that identifies your account in the hosted Connect button. Secret keys ride the Authorization header on each call:

Authorization: Bearer <YOUR_RINGUP_KEY>

Secret keys

Create one in your Ringup dashboard, under API Keys. Keys come in two kinds, and the same code works with either, so you promote by swapping the key:

Test keys (rk_test_...) run against test mode: the real API, no real money, every charge settling on Ringup’s test processor account. See Testing.
Live keys (rk_live_...) run against your real merchants and settle on their own processor.

The key picks the environment on every request, and every id you get back says which environment it belongs to (cs_test_… / cs_live_…), so a test object can never be read as a live one.

Pass it on every request

Every Ringup call, identify, create_checkout, charge, and the rest, takes the key as a Bearer token:

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", "amount_cents": 2500 }'

const res = 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: "mch_1fd0e6c96e6dcd7681f2",
    caller_phone: "+14155550142",
    amount_cents: 2500,
  }),
});

import requests

res = requests.post(
    "https://api.ringup.dev/v1/create_checkout",
    headers={"Authorization": "Bearer <YOUR_RINGUP_KEY>"},
    json={
        "merchant_id": "mch_1fd0e6c96e6dcd7681f2",
        "caller_phone": "+14155550142",
        "amount_cents": 2500,
    },
)

In an agent integration you set the key once and it rides every call:

Hosted, from the dashboard: Ringup writes your key into the payment tools it provisions for you, so it rides every call without you handling it.
In your agent (API): the key lives in the Authorization header of the Ringup tools or HTTP calls your agent makes, next to the other tool config.

Either way the key sits on your server or in the platform’s tool configuration, never in a value the model generates.

Your secret key can create charges. Keep it server-side. Never put it in client-side code, a prompt, a transcript, or a public repository, and never let the model see or type it. If a key leaks, roll it from the dashboard.

Publishable keys

A publishable key (pk_test_... / pk_live_...) identifies your account without authorizing anything sensitive: it starts a merchant connection from the hosted Connect button and nothing else. It is safe to embed in a page or an email, and the dashboard shows it whenever you need it. It cannot read data or create charges, so it needs none of the secret key’s handling rules.

Get started

Concepts

Developer integrations

Merchant integrations

Authentication

Secret keys

Pass it on every request

Publishable keys

Next steps

Testing

How it works

​Secret keys

​Pass it on every request

​Publishable keys

​Next steps

Testing

How it works

Secret keys

Pass it on every request

Publishable keys

Next steps