Criar cobrança

Cria uma cobrança PIX com split entre o vendedor e a plataforma, e devolve o payload copia-e-cola.

POST /v1/charges

cURL

simples

curl --request POST \
  --url https://api.usevext.com/v1/charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 10000,
  "description": "Curso de Vue 3",
  "customer": {
    "name": "João Comprador",
    "email": "[e-mail]",
    "document": "11144477735",
    "document_type": "CPF",
    "phone_ddd": "11",
    "phone_number": "987654321"
  }
}
'

201

criada

{
  "object": "charge",
  "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
  "status": "pending",
  "payment_method": "pix",
  "amount": 10000,
  "currency": "BRL",
  "platform_fee": 798,
  "net_amount": 9202,
  "refunded_amount": 0,
  "description": "Curso de Vue 3",
  "reference": "pedido-1042",
  "customer": {
    "name": "João Comprador",
    "email": "[e-mail]",
    "document": "111.***.***-35"
  },
  "pix": {
    "qr_code": "00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234",
    "expires_at": "2026-08-04T15:00:00+00:00",
    "end_2_end_id": null
  },
  "created_at": "2026-08-04T14:00:00+00:00",
  "paid_at": null,
  "expired_at": null,
  "refunded_at": null
}

Os valores aqui são inteiros em centavos: R$ 100,00 se envia como 10000. Decimais são recusados com 422, e o porquê está em Valores em centavos.

Envie Idempotency-Key nesta chamada e você pode repetir com tranquilidade depois de um erro de rede: a mesma chave devolve o recurso que já existe, em vez de criar um segundo. Veja Idempotência.

A resposta traz pix.qr_code, o payload copia-e-cola. A imagem do QR não é devolvida: você a gera localmente a partir do payload. Ver Checkout PIX de ponta a ponta.

Authorizations

Authorization · string · header · required

Chave secreta do vendedor, criada no painel em Desenvolvedores.

O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém.

A chave vai no servidor. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página.

Headers

Idempotency-Key · string

Identificador único da SUA tentativa. Use o mesmo valor ao repetir a requisição depois de um erro de rede.

Opcional, mas recomendado em toda criação de cobrança e estorno. Sem ele, uma repetição cria uma segunda cobrança.

Maximum string length: 255

Body

application/json

amount · integer<int64> · required

Valor total da cobrança, em centavos inteiros. R$ 100,00 = 10000. Um decimal aqui é recusado com 422.

Required range: x >= 1

customer · object · required

Show child attributes

description · string | null

Aparece para o comprador na tela de pagamento.

Maximum string length: 255

reference · string | null

Sua referência (número do pedido, id interno). Volta na consulta e nos webhooks, e serve de filtro em GET /v1/charges - é o que permite casar a cobrança com o seu pedido sem guardar o nosso id.

Maximum string length: 120

expires_in · integer | null · default: 3600

Validade do QR, em segundos. O piso de 60s evita uma cobrança que expira antes de o comprador abrir o aplicativo do banco.

Required range: 60 <= x <= 604800

items · object[] | null

Opcional. Sem itens, montamos um a partir de description.

Maximum array length: 100

Show child attributes

Response

201

application/json

Cobrança criada e aguardando pagamento.

object · string · required

Allowed value: "charge"

id · string · required

Código público da cobrança. Nunca é a chave primária: expor o autoincremento diria a qualquer cliente quantas vendas a plataforma inteira processou.

Example:

"ch_01k1y6r6m6q2x0p3d9v4t7c8n2"

status · enum<string> · required

Situação da cobrança. Todos os estados exceto pending são terminais - exceto os que ainda admitem estorno.

partially_refunded é estado próprio, e não um refunded com asterisco: tratar uma venda devolvida pela metade como estornada faria seu relatório descontar o valor inteiro.

Available options: pending, paid, expired, canceled, partially_refunded, refunded, failed

payment_method · enum<string> · required

Available options: pix

amount · integer<int64> · required

Valor cobrado, em centavos inteiros.

currency · string · required

Allowed value: "BRL"

platform_fee · integer<int64>

Nossa taxa, em centavos inteiros. Congelada na criação: reflete o contrato que valia quando a venda aconteceu, não o de hoje.

net_amount · integer<int64>

O que fica com o vendedor, em centavos inteiros (amount - platform_fee).

refunded_amount · integer<int64>

Total já devolvido ao comprador, em centavos inteiros. Acumulado entre estornos parciais.

description · string | null

reference · string | null

customer · object

O comprador, como devolvemos.

Show child attributes

pix · object

Show child attributes

created_at · string<date-time> | null

paid_at · string<date-time> | null

expired_at · string<date-time> | null

refunded_at · string<date-time> | null