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

# Criar um checkout

> Abre uma sessão de checkout hospedada para uma oferta e obtém a URL para onde enviar o comprador.

<Info>
  `POST /v1/checkouts`  ·  Requer o escopo `checkouts:write`
</Info>

Abre uma sessão de checkout para uma oferta. A resposta traz uma `checkout_url` — a página hospedada onde o comprador paga com Pix. Quando ele conclui, o `status` da sessão vira `completed`.

<Note>
  Ofertas recorrentes ainda não são suportadas no checkout — uma oferta `recurring` retorna `400` (`recurring_checkout_not_supported`). As sessões expiram 24 horas após a criação.
</Note>

## Parâmetros do corpo

<ParamField body="offer_id" type="string" required>
  A oferta a vender. Deve ser uma oferta ativa de um produto ativo.
</ParamField>

<ParamField body="customer_id" type="string">
  Um cliente existente (`cus_…`) a vincular. Deve estar ativo.
</ParamField>

<ParamField body="external_id" type="string">
  Sua referência para este checkout, de 1 a 255 caracteres. Único por conta — reutilize para tornar `POST /v1/checkouts` seguro de repetir (uma repetição retorna `409` em vez de uma segunda sessão).
</ParamField>

<ParamField body="success_url" type="string">
  Para onde a página hospedada envia o comprador após o pagamento. `http`/`https`, até 2048 caracteres.
</ParamField>

<ParamField body="cancel_url" type="string">
  Para onde o comprador vai se abandonar o checkout.
</ParamField>

<ParamField body="metadata" type="object">
  Pares chave–valor livres, devolvidos no objeto de checkout.
</ParamField>

## Requisição

```bash cURL theme={null}
curl --request POST https://api.moneydev.com.br/v1/checkouts \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "offer_id": "offer_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "customer_id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
    "external_id": "order_1042",
    "success_url": "https://loja.example.com/pedido/1042/ok",
    "cancel_url": "https://loja.example.com/pedido/1042"
  }'
```

## Resposta

`201 Created` com o [objeto de checkout](#objeto-de-checkout). Redirecione o comprador para a `checkout_url`.

```json theme={null}
{
  "id": "checkout_7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
  "object": "checkout",
  "customer_id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
  "external_id": "order_1042",
  "mode": "payment",
  "status": "open",
  "currency": "BRL",
  "amount_total_minor": 49900,
  "checkout_url": "https://pay.moneydev.com.br/c/8Xr2v9Qk1mNpZ...",
  "success_url": "https://loja.example.com/pedido/1042/ok",
  "cancel_url": "https://loja.example.com/pedido/1042",
  "metadata": {},
  "line_items": [
    {
      "id": "item_2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "object": "checkout_line_item",
      "product_id": "prod_4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "offer_id": "offer_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Plano Pro",
      "description": "Acesso completo por 12 meses",
      "offer_name": "Anual",
      "quantity": 1,
      "currency": "BRL",
      "unit_amount_minor": 49900,
      "total_amount_minor": 49900,
      "type": "one_time",
      "billing_interval": null,
      "interval_count": null,
      "metadata": {}
    }
  ],
  "expires_at": "2026-08-29T13:15:00.000Z",
  "completed_at": null,
  "created_at": "2026-08-28T13:15:00.000Z",
  "updated_at": "2026-08-28T13:15:00.000Z"
}
```

## Erros

| Status | `code` | Causa |
| - | - | - |
| `400` | `invalid_offer_id` | `offer_id` não é um ID `offer_` válido |
| `400` | `invalid_customer_id` | `customer_id` não é um ID `cus_` válido |
| `400` | `invalid_external_id` | `external_id` foi enviado vazio |
| `400` | `invalid_success_url` / `invalid_cancel_url` | A URL não é `http`/`https` |
| `400` | `recurring_checkout_not_supported` | A oferta é `recurring` |
| `404` | `offer_not_found` | Oferta ausente, inativa, arquivada, ou o produto dela não está ativo |
| `404` | `customer_not_found` | `customer_id` informado mas nenhum cliente ativo corresponde |
| `409` | `checkout_external_id_already_exists` | `external_id` já usado em outro checkout |

## Objeto de checkout

<ResponseField name="id" type="string">ID do checkout, com prefixo `checkout_`.</ResponseField>
<ResponseField name="object" type="string">Sempre `"checkout"`.</ResponseField>
<ResponseField name="customer_id" type="string | null">Cliente vinculado, ou `null`.</ResponseField>
<ResponseField name="external_id" type="string | null">Sua referência, ou `null`.</ResponseField>
<ResponseField name="mode" type="string">`payment`.</ResponseField>

<ResponseField name="status" type="string">
  `open`, `completed`, `expired` ou `canceled`. Leituras expiram automaticamente uma sessão `open` que passou de `expires_at`.
</ResponseField>

<ResponseField name="currency" type="string">Moeda ISO 4217.</ResponseField>
<ResponseField name="amount_total_minor" type="integer">Total em unidades menores.</ResponseField>
<ResponseField name="checkout_url" type="string">URL da página hospedada para o comprador.</ResponseField>
<ResponseField name="success_url" type="string | null">Redirecionamento pós-pagamento, ou `null`.</ResponseField>
<ResponseField name="cancel_url" type="string | null">Redirecionamento de abandono, ou `null`.</ResponseField>
<ResponseField name="metadata" type="object">Seus metadados.</ResponseField>

<ResponseField name="line_items" type="array">
  Os itens vendidos. Cada um tem `id` (`item_…`), `product_id`, `offer_id`, `name`, `description`, `offer_name`, `quantity`, `currency`, `unit_amount_minor`, `total_amount_minor`, `type`, `billing_interval`, `interval_count` e `metadata`.
</ResponseField>

<ResponseField name="expires_at" type="string">Expiração em ISO 8601 (24 h após a criação).</ResponseField>
<ResponseField name="completed_at" type="string | null">Data/hora de conclusão em ISO 8601, ou `null`.</ResponseField>
<ResponseField name="created_at" type="string">Data/hora de criação em ISO 8601.</ResponseField>
<ResponseField name="updated_at" type="string">Data/hora da última alteração em ISO 8601.</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.