TuCapiDocs

API reference

Charges

A charge is what you create: an amount with a checkout URL. It can be paid once.

Endpoints

The Charge object

Object fields, as the API returns them.

  • objectstring
    Always charge.
  • idstring (uuid)
    Charge id.
  • statusstring
    Charge status.
    Possible values:openpaidexpiredcanceledpaused
  • amountstring (decimal)
    Amount in USD.
  • currencystring
    Always USD.
  • descriptionstringNullable
    What your customer sees.
  • referencestringNullable
    Your reference.
  • metadataobject
    Your data, as you sent it.
  • allowedMethodsstring[]
    Methods your customer can choose.
    Possible values:paypalzellecard
  • checkoutUrlstring (url)
    Checkout URL. Send your customer here.
  • embedUrlstring (url)
    The same charge for an iframe. Only loads on your authorized sites.
  • expiresAtstring (date-time)Nullable
    When the charge expires.
  • paidAtstring (date-time)Nullable
    When it was paid.
  • createdAtstring (date-time)
    When it was created.
  • ordersOrder[]
    The charge's orders, up to 20, newest first.
The Charge object
JSON
{  "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"    }  ]}

Create a charge

POST/v1/charges

Creates a single-use charge and returns checkoutUrl. When your customer picks a method an order is created and you get order.created; once the payment is confirmed, order.paid.

Scopeorders:write

Headers

  • Idempotency-KeystringOptional
    A unique id for the operation. Recommended on every POST. See Idempotency.
    Up to 255 characters

Request body

  • amountstring | numberRequired
    Greater than 0, up to 2 decimals, up to 1,000,000. As a string (recommended) or a number.
  • currencystringOptional
    USD only.
    Default: USDPossible values:USD
  • descriptionstringOptional
    What your customer sees at checkout.
    Up to 200 characters
  • referencestringOptional
    Your order or invoice number. Unique per merchant: reusing it returns 409 reference_exists.
    Up to 120 characters
  • metadataobjectOptional
    Up to 20 keys and 4 KB. Returned as is.
  • allowedMethodsstring[]Optional
    Methods your customer can choose. Defaults to all.
    Possible values:paypalzellecard
  • expiresAtstring (date-time)Optional
    Up to one year. After it, checkout stops accepting payments.

Returns

Returns a Charge object.

Error responses

400401403409429
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": "Pedido #1042",    "reference": "ORD-1042",    "metadata": {      "customerId": "c_88"    },    "allowedMethods": [      "paypal",      "card"    ],    "expiresAt": "2026-09-16T12:00:00Z"  }'
201 Response
JSON
{  "object": "charge",  "id": "9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e",  "status": "open",  "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": null,  "createdAt": "2026-09-15T18:42:07Z",  "orders": []}

Retrieve a charge

GET/v1/charges/{id}

Returns the charge with its orders: up to 20, newest first.

Scopeorders:read

Path parameters

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

Returns

Returns a Charge object.

Error responses

401403404429
curl "https://api.business.tucapi.com/v1/charges/9b1e2d3c-4f5a-4b6c-8d7e-0f1a2b3c4d5e" \  -H "Authorization: Bearer $TUCAPI_KEY"
200 Response
JSON
{  "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"    }  ]}