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
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"
}'{
"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
Create a secret key
In your dashboard, under Developers › API keys. Type Secret, Live environment, only the scopes you need.
- 2
Create the charge
POST /v1/charges with an Idempotency-Key and your order number in reference.
- 3
Send your customer
Redirect to checkoutUrl, or embed embedUrl in your site on the domains you authorize.
- 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_…
| Endpoint | What it does | Scope |
|---|---|---|
| POST/v1/charges | Creates a charge and returns the payment link | orders:write |
| GET/v1/charges/{id} | Retrieves a charge and its orders | orders:read |
| GET/v1/orders | Lists orders with filters and cursor-based pagination | orders:read |
| GET/v1/orders/{id} | Retrieves an order: method, amount, net and status | orders:read |
| GET/v1/balance | Available 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.
| Event | When it's sent |
|---|---|
| order.created | Your customer chose a payment method |
| order.paid | The payment was confirmed and the net amount credited |
| order.expired | The order expired unpaid |
| payout.created | You requested a payout |
| payout.completed | The payout was completed |
| payout.failed | The payout failed and the balance was returned |
| webhook.test | Manual 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.
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");
}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: 1API 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.