What Circuit is

Circuit is a two-sided payment processor. Payers (in Africa or US/CA) pay in via YellowCard local rails (mobile money / bank) or Cybrid; merchants register on the Circuit website, complete KYB in the dashboard, link a cashout account, and get paid in USD (Cybrid ACH/wire) or local currency (YellowCard).

Merchants sign up and log in at circuit.com — account creation is not part of the integration API. Once you have an account, you integrate payments using API keys issued from the dashboard.

Two callers, two auth models — don't mix them

Response envelope — every response is { "success": boolean, "data": {…}, "message"?: string }. Errors are { "success": false, "error": { "code", "category", "message", "details"? } }.

Quickstart

1. Create a Circuit account at /signup and complete onboarding in the dashboard (KYB + cashout account). See the Merchant Onboarding guide for the full journey.
2. Issue test keys from the dashboard. sk_test_* / pk_test_* work immediately in sandbox — no production approval required.
3. Accept your first payment. From your backend, create a hosted checkout session or PaymentIntent with your secret key:

POST /checkout/sessions
Authorization: Bearer sk_test_...
Content-Type: application/json

{ "amountUSD": 5.00, "successUrl": "https://yourstore.com/success",
  "cancelUrl": "https://yourstore.com/cart", "clientReferenceId": "order_1001" }

Redirect the payer to the returned hostedUrl, or follow the full integration paths in the Merchant Integration guide.

4. Configure a webhook endpoint in the dashboard and verify the Circuit-Signature on every event. Fulfill orders on the webhook — not on the browser redirect.
5. Switch to live keys once your account is production-ready (KYB verified and a cashout account linked).

Authentication & keys

Issue keys from the dashboard. The secret is shown once — store it securely. Rotate compromised keys from dashboard settings.

Base URLs: API https://api.circuit.com · hosted checkout https://checkout.circuit.com. Use test keys against your sandbox/dev base URL.

sk_test_* / pk_test_* always work in sandbox. sk_live_* / pk_live_* are rejected until your account passes the production gate (KYB + cashout account). See Sandbox vs production.

Webhooks

Circuit delivers payment events to an HTTPS endpoint you configure in the dashboard. This is how your backend learns a payment settled — the payer landing on successUrl is not proof of payment.

For setup details, event types, and verification examples, see Confirm the result in the Merchant Integration guide.

Registered domains

If your integration calls Circuit from the browser with a publishable key, your origin must be allowlisted. Request domain approval from the dashboard (Settings → Domains). Operator-reviewed before going live.

Taking payments

Circuit supports two integration paths on the same PaymentIntent model:

• Hosted checkout (recommended) — your backend creates a session; Circuit hosts the payer flow; redirect or share the hostedUrl as a payment link.
• Direct API — your backend creates a PaymentIntent; your frontend or native app drives payer steps with the publishable key + client_secret.

Step-by-step guides, SDK packages, payment links, and the integration checklist are in the Merchant Integration guide.

Errors & Security

• Idempotency: POST /v1/payment-intents requires an Idempotency-Key header. Reuse the same key to safely retry a create.
• Common codes: VALIDATION_ERROR (400), UNAUTHORIZED/INVALID_API_KEY/INVALID_CLIENT_SECRET (401), FORBIDDEN (403 — incl. the production gate, with details.missingSteps), *_NOT_FOUND (404), OPTIMISTIC_LOCK_ERROR (409 — re-fetch and retry).
• Webhooks fail closed: verify Circuit-Signature before trusting a payload.
• Never expose secret keys in client-side code, mobile apps, or public repos.