TuCapiDocs

API reference

Orders

An order is a single payment attempt. It's created when your customer picks a method at checkout.

Endpoints

The Order object

Object fields, as the API returns them.

  • objectstring
    Always order.
  • idstring (uuid)
    Order id.
  • chargeIdstring (uuid)Nullable
    Id of the charge it belongs to.
  • merchantOrderRefstring
    Internal order reference. It's the merchantOrderRef in webhooks.
  • statusstring
    Status. A pending order past its expiresAt shows as expired; a late payment can still move it to paid.
    Possible values:pendingpaidexpiredfailedrefundeddisputed
  • paymentMethodstring
    Method your customer chose.
    Possible values:paypalzellecard
  • amountstring (decimal)
    Amount in USD.
  • currencystring
    Always USD.
  • feesobject
    Fee applied.
  • fees.ratestring
    Rate as a fraction ("0.035" is 3.5%).
  • fees.fixedstring (decimal)
    Fixed fee.
  • netAmountUsdtstringNullable
    Amount credited to your balance, in USDT. Only when paid.
  • externalRefstringNullable
    Payment id in the method (PayPal order id, PaymentIntent…).
  • payerobjectNullable
    Payer details, when available.
  • payer.emailstringNullable
    Payer email.
  • payer.namestringNullable
    Payer name.
  • descriptionstringNullable
    Description.
  • metadataobject
    Extra data.
  • expiresAtstring (date-time)
    When the order expires.
  • paidAtstring (date-time)Nullable
    When it was paid.
  • createdAtstring (date-time)
    When it was created.
The Order object
JSON
{  "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"}

List orders

GET/v1/orders

Newest first, with cursor pagination. While hasMore is true, call again with cursor=nextCursor.

Scopeorders:read

Query parameters

  • limitintegerOptional
    Results per page.
    Default: 25Between 1 and 100
  • cursorstringOptional
    The nextCursor from the previous page.
  • statusstringOptional
    Filter by status. pending leaves out expired ones; expired includes pending orders whose expiresAt has passed.
    Possible values:pendingpaidexpiredfailedrefundeddisputed
  • chargestring (uuid)Optional
    Only orders for this charge.

Returns

Returns a paginated list of Order objects.

Error responses

400401403429
curl "https://api.business.tucapi.com/v1/orders?limit=50&status=paid" \  -H "Authorization: Bearer $TUCAPI_KEY"
200 Response
JSON
{  "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…"}

Retrieve an order

GET/v1/orders/{id}

Returns one order by its id.

Scopeorders:read

Path parameters

  • idstring (uuid)Required
    Resource id (UUID).

Returns

Returns a Order object.

Error responses

401403404429
curl "https://api.business.tucapi.com/v1/orders/c9227f9b-13f4-4e9c-8fe0-4644e62b83cd" \  -H "Authorization: Bearer $TUCAPI_KEY"
200 Response
JSON
{  "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"}