TuCapiDocs

Payments

Retrieve charges and orders

Charge and order statuses, how to retrieve them, paginate and reconcile your payments.

Charge and order

A charge is what you create. An order is each payment attempt on that charge.

If your customer tries PayPal and then a card, the charge has two orders. Only one can end up paid.

GET /v1/charges/{id} returns the charge with its orders: up to 20, newest first.

curl "https://api.business.tucapi.com/v1/charges/9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e" \  -H "Authorization: Bearer $TUCAPI_KEY"
Response
{  "object": "charge",  "id": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",  "status": "paid",  "amount": "125.00",  "currency": "USD",  "description": "Pedido #1042",  "reference": "ORD-1042",  "metadata": {    "customerId": "c_88"  },  "allowedMethods": [    "paypal",    "card"  ],  "checkoutUrl": "https://pay.tucapi.com/k7x2m9qz",  "embedUrl": "https://pay.tucapi.com/embed/k7x2m9qz",  "expiresAt": "2026-09-16T12:00:00Z",  "paidAt": "2026-09-15T18:50:31Z",  "createdAt": "2026-09-15T18:42:07Z",  "orders": [    {      "object": "order",      "id": "c9227f9b-13f4-4e9c-8fe0-4644e62b83cd",      "chargeId": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",      "merchantOrderRef": "MO-k7x2m9qz-1a2b3c4d",      "status": "paid",      "paymentMethod": "paypal",      "amount": "125.00",      "currency": "USD",      "fees": {        "rate": "0.035",        "fixed": "0.30"      },      "netAmountUsdt": "120.33",      "externalRef": "5O190127TN364715T",      "payer": {        "email": "ana@example.com",        "name": null      },      "expiresAt": "2026-09-15T19:12:07Z",      "paidAt": "2026-09-15T18:50:31Z",      "createdAt": "2026-09-15T18:42:07Z"    }  ]}

Statuses

Charge

statusMeaning
openWaiting for payment.
paidOne of its orders was paid.
expiredexpiresAt passed without a payment.
canceledYou canceled it in the dashboard.
pausedPaused in the dashboard.

Order

statusMeaning
pendingWaiting for the payment to be confirmed.
paidPayment confirmed. The net amount is in your balance.
expiredExpired without being paid.
failedThe payment failed.
refundedRefunded.
disputedUnder dispute.

An expired order can still be paid

A pending order past its expiresAt shows as expired. If the payment arrives late (it happens with PayPal), it can still move to paid. Don't write it off until you get order.expired.

List orders

GET /v1/orders returns your orders, newest first.

  • limitintegerOptional
    Between 1 and 100. Defaults to 25.
  • cursorstringOptional
    The nextCursor from the previous page.
  • statusstringOptional
    pending, paid, expired, failed, refunded or disputed. pending leaves out expired ones; expired includes expired pending ones.
  • chargestring (uuid)Optional
    Only orders for that charge.
curl "https://api.business.tucapi.com/v1/orders?limit=50&status=paid" \  -H "Authorization: Bearer $TUCAPI_KEY"
Response
{  "object": "list",  "data": [    {      "object": "order",      "id": "c9227f9b-13f4-4e9c-8fe0-4644e62b83cd",      "chargeId": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",      "merchantOrderRef": "MO-k7x2m9qz-1a2b3c4d",      "status": "paid",      "paymentMethod": "paypal",      "amount": "125.00",      "currency": "USD",      "fees": {        "rate": "0.035",        "fixed": "0.30"      },      "netAmountUsdt": "120.33",      "externalRef": "5O190127TN364715T",      "payer": {        "email": "ana@example.com",        "name": null      },      "expiresAt": "2026-09-15T19:12:07Z",      "paidAt": "2026-09-15T18:50:31Z",      "createdAt": "2026-09-15T18:42:07Z"    }  ],  "hasMore": true,  "nextCursor": "MjAyNi0wOS0xNVQxODo0Mjow…"}

Paginate

  1. 1Request the first page without cursor.
  2. 2If hasMore is true, call again with cursor=<nextCursor>.
  3. 3Stop when hasMore is false.

The cursor is stable. Orders that arrive while you paginate don't shift pages or show up twice.

Reconcile

  • Walk GET /v1/orders?status=paid once a day.
  • Use the order id (or externalRef) as the key.
  • netAmountUsdt is what was credited to your balance.
curl "https://api.business.tucapi.com/v1/orders/c9227f9b-13f4-4e9c-8fe0-4644e62b83cd" \  -H "Authorization: Bearer $TUCAPI_KEY"
Response
{  "object": "order",  "id": "c9227f9b-13f4-4e9c-8fe0-4644e62b83cd",  "chargeId": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",  "merchantOrderRef": "MO-k7x2m9qz-1a2b3c4d",  "status": "paid",  "paymentMethod": "paypal",  "amount": "125.00",  "currency": "USD",  "fees": {    "rate": "0.035",    "fixed": "0.30"  },  "netAmountUsdt": "120.33",  "externalRef": "5O190127TN364715T",  "payer": {    "email": "ana@example.com",    "name": null  },  "expiresAt": "2026-09-15T19:12:07Z",  "paidAt": "2026-09-15T18:50:31Z",  "createdAt": "2026-09-15T18:42:07Z"}