TuCapi Business · Developers

Accept US dollar payments from your code.

A REST API to create charges, retrieve orders and read your balance. Secret keys with scoped permissions, idempotency on every write, and signed webhooks so you hear about every payment.

OpenAPI 3
REST + JSON
OpenAPI 3
curl · Node · Python · PHP
4 languages
curl · Node · Python · PHP
documentation
en / es
documentation
curlCreate a charge
curl -X POST https://api.business.tucapi.com/v1/charges \
  -H "Authorization: Bearer $TUCAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORD-1042" \
  -d '{
    "amount": "125.00",
    "description": "Order #1042",
    "reference": "ORD-1042",
    "metadata": { "customerId": "c_88" },
    "allowedMethods": ["paypal", "card"],
    "expiresAt": "2026-09-16T12:00:00Z"
  }'
JSONResponse · 201 (excerpt)
{
  "object": "charge",
  "id": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",
  "status": "open",
  "amount": "125.00",
  "currency": "USD",
  "checkoutUrl": "https://pay.tucapi.com/k7x2m9qz",
  "embedUrl": "https://pay.tucapi.com/embed/k7x2m9qz",
  "expiresAt": "2026-09-16T12:00:00Z"
}

Quickstart

Your first integration in four steps

  1. 1

    Create a secret key

    In your dashboard, under Developers › API keys. Type Secret, Live environment, only the scopes you need.

  2. 2

    Create the charge

    POST /v1/charges with an Idempotency-Key and your order number in reference.

  3. 3

    Send your customer

    Redirect to checkoutUrl, or embed embedUrl in your site on the domains you authorize.

  4. 4

    Confirm by webhook

    Receive order.paid, verify the signature and mark the order as paid.

API

Available endpoints

Base URL: https://api.business.tucapi.com/v1 · Authentication: Authorization: Bearer tcb_sk_live_…

EndpointWhat it doesScope
POST/v1/chargesCreates a charge and returns the payment linkorders:write
GET/v1/charges/{id}Retrieves a charge and its ordersorders:read
GET/v1/ordersLists orders with filters and cursor-based paginationorders:read
GET/v1/orders/{id}Retrieves an order: method, amount, net and statusorders:read
GET/v1/balanceAvailable and pending balance (USDT, pegged 1:1 to the dollar)balance:read
300
reads per minute, per key
60
writes per minute, per key
24 h
Idempotency-Key validity
6
attempts per webhook, over up to 24 h

Webhooks

We notify you of every payment, with a verifiable signature

Every event arrives with the TuCapi-Signature: t=…,v1=… header. The signature is an HMAC-SHA256 of t + "." + body using your secret. Reject events with a timestamp more than 5 minutes off.

EventWhen it's sent
order.createdYour customer chose a payment method
order.paidThe payment was confirmed and the net amount credited
order.expiredThe order expired unpaid
payout.createdYou requested a payout
payout.completedThe payout was completed
payout.failedThe payout failed and the balance was returned
webhook.testManual test from the dashboard

If your endpoint doesn't return a 2xx within 10 seconds, we retry after 1 min, 5 min, 30 min, 2 h and 24 h. You can also resend an event manually from the dashboard.

Node.jsVerify the signature
const crypto = require("crypto");

function verifyTuCapi(rawBody, header, secret, toleranceSec = 300) {
  const parts = header.split(",").map((p) => p.trim());
  const t = parts.find((p) => p.startsWith("t="))?.slice(2);
  const v1 = parts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
  if (!t || v1.length === 0) throw new Error("invalid header");
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) {
    throw new Error("outside tolerance window");
  }
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest("hex");
  const ok = v1.some(
    (sig) =>
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex")),
  );
  if (!ok) throw new Error("invalid signature");
}
Also available in Python, PHP and Go in the docs.
HTTPWebhook headers
POST /webhooks/tucapi HTTP/1.1
Content-Type: application/json
TuCapi-Signature: t=1726000000,v1=5f1a…9c
TuCapi-Event-Id: evt_2b1c9d0e4f5a4a6b8c7d9e0f1a2b3c4d
TuCapi-Event-Type: order.paid
TuCapi-Attempt: 1

API keys

Least-privilege access for every integration

Secret keys

Format tcb_sk_live_…. Shown only once; we store just a hash, never the key itself. Only the account owner can create them.

Scopes

orders:write, orders:read and balance:read. If a key is missing the scope an endpoint requires, the API returns 403 insufficient_scope.

Embedded checkout

Show the payment inside your site with embedUrl. It only works on the domains you authorize in your dashboard.

The API currently runs in live mode only: every paid charge is real.

Documentation

Everything you need to integrate

Start building

Open your business account, create your key and make your first API charge.