> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.certopaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create New Payment Order — POST /api/orders Guide

> POST /api/orders — Create a payment order in CertoPay linking a customer to an amount in centavos. Returns the orderId for payment processing.

Use this endpoint to create a new payment order in CertoPay. An order represents the commercial intent to charge a specific amount to a registered customer, and must be created before any payment method (Pix, boleto, or credit card) can be applied. You must supply a valid `customerId` obtained from `POST /api/customers`, along with the charge amount expressed in **centavos** (the smallest Brazilian currency unit). The returned order `id` becomes the `orderId` you will reference when processing the actual payment.

## Request

<ParamField header="X-Api-Key" type="string" required>
  Your CertoPay secret API key. Include it in every request as `X-Api-Key: sk_live_sua_chave_aqui`.
</ParamField>

<ParamField body="customerId" type="string" required>
  The UUID of the customer being charged. This is the `id` returned by `POST /api/customers`. The customer must already exist in your account.
</ParamField>

<ParamField body="amount" type="integer" required>
  Total charge amount in **centavos** (Brazilian cents). For example, `29700` represents R\$ 297,00. Must be a positive integer greater than zero.
</ParamField>

## Response

A successful request returns **HTTP 201 Created** with the newly created order object.

<ResponseField name="id" type="string">
  Unique UUID assigned to this order. **Save this value** — it is required as `orderId` in all downstream payment requests.
</ResponseField>

<ResponseField name="customerId" type="string">
  UUID of the customer linked to this order, echoed from the request.
</ResponseField>

<ResponseField name="amount" type="integer">
  Charge amount in centavos, echoed from the request.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the order. Newly created orders always start as `"PENDING"`. Other possible values as the order progresses: `"PAID"`, `"CANCELLED"`, `"EXPIRED"`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp recording when the order was created (e.g. `"2026-06-26T10:00:00Z"`).
</ResponseField>

<Note>
  Save the `id` returned in this response — it becomes the `orderId` required in all subsequent payment requests (Pix, boleto, and credit card). Without it you cannot charge the customer.
</Note>

## Example

```bash theme={null}
curl -X POST https://v2.certopaybrasil.com/api/orders \
  -H "X-Api-Key: sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "uuid-do-customer",
    "amount": 29700
  }'
```

```json 201 Created theme={null}
{
  "id": "uuid-do-pedido",
  "customerId": "uuid-do-customer",
  "amount": 29700,
  "status": "PENDING",
  "createdAt": "2026-06-26T10:00:00Z"
}
```