> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar cobrança
> Cria uma cobrança PIX com split entre o vendedor e a plataforma, e devolve o payload copia-e-cola.
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](/essenciais/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](/essenciais/idempotencia).
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](/receitas/checkout-pix).
## OpenAPI
````yaml api-reference/openapi.yaml POST /v1/charges
openapi: 3.1.0
info:
title: Vext - API de pagamentos PIX com split
version: 1.0.0
summary: Cobranças PIX, estornos e saldo do vendedor.
description: |
API pública do gateway. Todo endpoint desta versão vive sob `/v1`.
Quatro regras valem para toda chamada. Cada uma tem uma página própria
nos guias, com exemplos nas quatro linguagens.
- **Dinheiro é sempre centavos inteiros.** R$ 100,00 se envia como
`10000`; um decimal devolve `422`. Ver
[Valores em centavos](/essenciais/valores-em-centavos).
- **A chave secreta vai no header e fica no servidor.** Cada chave
carrega escopos; fora do escopo devolve `403`, e não `401`. Ver
[Autenticação](/essenciais/autenticacao).
- **Envie `Idempotency-Key` em todo `POST`.** Repetir com a mesma chave
devolve a resposta gravada em vez de criar um segundo recurso. Ver
[Idempotência](/essenciais/idempotencia).
- **Trate os erros pelo `code`**, nunca pela `message` - o código é
contrato, o texto pode ser reescrito a qualquer momento. Ver
[Erros](/essenciais/erros).
contact:
name: Suporte Vext
email: suporte@usevext.com
servers:
- url: https://api.usevext.com
description: Produção
security:
- apiKey: []
tags:
- name: Cobranças
description: Criação, consulta e estorno de cobranças PIX.
- name: Saldo
description: Quanto o vendedor tem e quanto pode sacar.
paths:
/v1/charges:
post:
tags:
- Cobranças
summary: Criar cobrança PIX
description: |
Cria uma cobrança PIX com split entre o vendedor e a plataforma. A
resposta traz o payload copia-e-cola (`pix.qr_code`) já pronto para
exibir ao comprador.
A imagem do QR **não** é devolvida: ela é derivada do payload na
hora de exibir, e mandar um PNG em base64 em toda resposta
multiplicaria o corpo por algo que você gera localmente.
operationId: createCharge
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeRequest'
examples:
simples:
summary: Cobrança de R$ 100,00
value:
amount: 10000
description: Curso de Vue 3
reference: pedido-1042
customer:
name: João Comprador
email: joao@exemplo.com.br
document: '11144477735'
document_type: CPF
phone_ddd: '11'
phone_number: '987654321'
comItens:
summary: Com itens discriminados
description: |
A soma de `quantity * amount` de todos os itens precisa
bater exatamente com `amount`. Sem essa conferência o
comprador veria um total diferente da soma do que está
levando.
value:
amount: 10000
expires_in: 1800
customer:
name: Maria Compradora
document: '11144477735'
items:
- code: curso-vue
description: Curso de Vue 3
quantity: 1
amount: 6000
- code: ebook
description: E-book de apoio
quantity: 2
amount: 2000
responses:
'201':
description: Cobrança criada e aguardando pagamento.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
examples:
criada:
$ref: '#/components/examples/ChargePendente'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/UnprocessableCharge'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
$ref: '#/components/responses/ProviderUnavailable'
'503':
$ref: '#/components/responses/PlatformUnavailable'
security:
- apiKey:
- charges:write
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: |
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.
schema:
type: string
maxLength: 255
example: pedido-1042
schemas:
CreateChargeRequest:
type: object
required:
- amount
- customer
properties:
amount:
allOf:
- $ref: '#/components/schemas/Cents'
minimum: 1
description: |
Valor total da cobrança, em **centavos inteiros**. R$ 100,00 =
`10000`. Um decimal aqui é recusado com `422`.
description:
type:
- string
- 'null'
maxLength: 255
description: Aparece para o comprador na tela de pagamento.
reference:
type:
- string
- 'null'
maxLength: 120
description: |
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`.
expires_in:
type:
- integer
- 'null'
minimum: 60
maximum: 604800
default: 3600
description: |
Validade do QR, em segundos. O piso de 60s evita uma cobrança
que expira antes de o comprador abrir o aplicativo do banco.
customer:
$ref: '#/components/schemas/Customer'
items:
type:
- array
- 'null'
maxItems: 100
items:
$ref: '#/components/schemas/ChargeItem'
description: |
Opcional. Sem itens, montamos um a partir de `description`.
Charge:
type: object
required:
- object
- id
- status
- payment_method
- amount
- currency
properties:
object:
type: string
const: charge
id:
type: string
description: |
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:
$ref: '#/components/schemas/ChargeStatus'
payment_method:
type: string
enum:
- pix
amount:
allOf:
- $ref: '#/components/schemas/Cents'
description: Valor cobrado, em centavos inteiros.
currency:
type: string
const: BRL
platform_fee:
allOf:
- $ref: '#/components/schemas/Cents'
description: |
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:
allOf:
- $ref: '#/components/schemas/Cents'
description: |
O que fica com o vendedor, em centavos inteiros
(`amount - platform_fee`).
refunded_amount:
allOf:
- $ref: '#/components/schemas/Cents'
description: |
Total já devolvido ao comprador, em centavos inteiros. Acumulado
entre estornos parciais.
description:
type:
- string
- 'null'
reference:
type:
- string
- 'null'
customer:
$ref: '#/components/schemas/CustomerSummary'
pix:
type: object
properties:
qr_code:
type:
- string
- 'null'
description: |
Payload copia-e-cola do PIX. Gere a imagem do QR a partir
dele - não devolvemos PNG.
expires_at:
type:
- string
- 'null'
format: date-time
end_2_end_id:
type:
- string
- 'null'
description: |
Identificador da transação no Sistema de Pagamentos
Brasileiro. Aparece depois do pagamento e é o que o banco do
comprador reconhece.
created_at:
type:
- string
- 'null'
format: date-time
paid_at:
type:
- string
- 'null'
format: date-time
expired_at:
type:
- string
- 'null'
format: date-time
refunded_at:
type:
- string
- 'null'
format: date-time
Cents:
type: integer
format: int64
description: |
Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
Nunca decimal, nunca string.
Customer:
type: object
required:
- name
properties:
name:
type: string
maxLength: 120
example: João Comprador
email:
type:
- string
- 'null'
format: email
maxLength: 180
example: joao@exemplo.com.br
document:
type:
- string
- 'null'
maxLength: 20
description: |
CPF ou CNPJ. Pontuação é aceita e descartada - guardamos apenas
os dígitos.
example: 111.444.777-35
document_type:
type:
- string
- 'null'
enum:
- CPF
- CNPJ
- PASSPORT
- null
phone_ddd:
type:
- string
- 'null'
maxLength: 3
example: '11'
phone_number:
type:
- string
- 'null'
maxLength: 12
example: '987654321'
ChargeItem:
type: object
required:
- description
- quantity
- amount
properties:
code:
type:
- string
- 'null'
maxLength: 60
description: Seu código do produto.
description:
type: string
maxLength: 180
quantity:
type: integer
minimum: 1
amount:
allOf:
- $ref: '#/components/schemas/Cents'
description: |
Valor **unitário** em centavos inteiros. A soma de
`quantity * amount` de todos os itens precisa ser exatamente
igual ao `amount` da cobrança.
ChargeStatus:
type: string
description: |
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.
enum:
- pending
- paid
- expired
- canceled
- partially_refunded
- refunded
- failed
x-labels:
pending: Aguardando pagamento
paid: Pago
expired: Expirado
canceled: Cancelado
partially_refunded: Estornado em parte
refunded: Estornado
failed: Falhou
CustomerSummary:
type: object
description: O comprador, como devolvemos.
properties:
name:
type:
- string
- 'null'
email:
type:
- string
- 'null'
document:
type:
- string
- 'null'
description: |
Mascarado. Você já enviou o documento; devolvê-lo inteiro em
toda consulta espalharia o dado sem nenhum ganho.
example: 111.***.***-35
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
- details
properties:
type:
type: string
description: |
Família do erro. Responde "de quem é o problema e o que
fazer": `invalid_request_error` se corrige mudando a
chamada, `authentication_error` trocando a chave, e
`api_error` é nosso - repita, não reescreva.
enum:
- authentication_error
- permission_error
- invalid_request_error
- idempotency_error
- not_found_error
- rate_limit_error
- api_error
code:
type: string
description: |
Código estável do erro. **Trate por ele.** A `message` pode
ser reescrita a qualquer momento; o código, não.
message:
type: string
description: Explicação em português, para leitura humana.
details:
type: object
description: |
Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
campos recusados e suas mensagens.
additionalProperties: true
headers:
IdempotentReplayed:
description: |
Presente com valor `true` quando o corpo devolvido é uma resposta
**gravada**, e não um recurso novo. Nada foi criado nesta chamada.
schema:
type: string
enum:
- 'true'
examples:
ChargePendente:
summary: Cobrança criada, aguardando pagamento
value:
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: joao@exemplo.com.br
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
responses:
BadRequest:
description: Requisição malformada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
chaveLonga:
summary: idempotency_key_too_long
value:
error:
type: invalid_request_error
code: idempotency_key_too_long
message: A chave de idempotência deve ter no máximo 255 caracteres.
details: {}
Unauthorized:
description: |
Chave ausente, desconhecida, revogada ou expirada. A revogada é
distinguida da inexistente na MENSAGEM, nunca no status: quem
integra precisa saber que a chave existiu e foi desligada, e quem
está adivinhando tokens não aprende nada com isso.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ausente:
summary: missing_api_key
value:
error:
type: authentication_error
code: missing_api_key
message: 'Envie a chave em Authorization: Bearer sk_live_...'
details: {}
invalida:
summary: invalid_api_key
value:
error:
type: authentication_error
code: invalid_api_key
message: Chave de API inválida.
details: {}
revogada:
summary: revoked_api_key
value:
error:
type: authentication_error
code: revoked_api_key
message: >-
Esta chave de API foi revogada. Gere uma nova em
Desenvolvedores.
details: {}
expirada:
summary: expired_api_key
value:
error:
type: authentication_error
code: expired_api_key
message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
details: {}
Forbidden:
description: |
A chave é válida, mas não tem o escopo do endpoint. `403` e não
`401` de propósito: `401` diria "sua chave está errada" a quem tem
a chave certa.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
escopo:
summary: insufficient_scope
value:
error:
type: permission_error
code: insufficient_scope
message: Esta chave não tem o escopo [refunds:write].
details:
required_ability: refunds:write
abilities:
- charges:read
- charges:write
IdempotencyConflict:
description: Conflito de chave de idempotência.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
reusada:
summary: idempotency_key_reused
description: |
A chave já foi usada com outro corpo. Devolver a resposta
antiga faria você acreditar que cobrou o valor novo.
value:
error:
type: idempotency_error
code: idempotency_key_reused
message: >-
Esta chave de idempotência já foi usada com um corpo
diferente. Use uma chave nova.
details: {}
emAndamento:
summary: idempotency_key_in_progress
value:
error:
type: idempotency_error
code: idempotency_key_in_progress
message: >-
Uma requisição com esta chave ainda está em processamento.
Tente novamente em instantes.
details: {}
UnprocessableCharge:
description: |
A requisição está bem formada, mas foi recusada por uma regra de
negócio. Todos os `code` abaixo são estáveis.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
validacao:
summary: validation_failed
value:
error:
type: invalid_request_error
code: validation_failed
message: Alguns campos não passaram na validação.
details:
customer.name:
- O campo nome é obrigatório.
abaixoDoMinimo:
summary: amount_below_minimum
value:
error:
type: invalid_request_error
code: amount_below_minimum
message: O valor está abaixo do mínimo permitido.
details: {}
acimaDoMaximo:
summary: amount_above_maximum
value:
error:
type: invalid_request_error
code: amount_above_maximum
message: O valor está acima do máximo permitido.
details: {}
itens:
summary: items_do_not_match_amount
value:
error:
type: invalid_request_error
code: items_do_not_match_amount
message: A soma dos itens deve ser igual ao valor da cobrança.
details: {}
vendedor:
summary: seller_not_approved
description: |
O cadastro do vendedor não está aprovado para transacionar.
Nada na chamada resolve - o caminho é o painel.
value:
error:
type: invalid_request_error
code: seller_not_approved
message: Este vendedor não pode transacionar no momento.
details: {}
provedor:
summary: provider_rejected
description: |
O provedor recusou o conteúdo. A mensagem crua dele nunca
sai daqui - cita ids e endpoints que não existem no nosso
contrato.
value:
error:
type: invalid_request_error
code: provider_rejected
message: >-
O provedor de pagamento recusou esta cobrança. Confira os
dados do comprador e do valor.
details: {}
RateLimited:
description: |
Requisições demais.
Há três limites, por minuto: um por IP antes da autenticação, e
depois um de leitura e um de escrita, ambos por CHAVE - o excesso
de uma integração não consome a cota das outras do mesmo
vendedor. A escrita é bem mais apertada porque cada cobrança
criada vira uma chamada ao provedor.
`Retry-After` diz em quantos segundos voltar. Os cabeçalhos
`X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
permitem desacelerar antes de bater no limite.
headers:
Retry-After:
description: Segundos até a cota ser reposta.
schema:
type: integer
X-RateLimit-Limit:
description: Requisições permitidas por minuto neste balde.
schema:
type: integer
X-RateLimit-Remaining:
description: Quantas ainda cabem no minuto corrente.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cota:
summary: too_many_requests
value:
error:
type: rate_limit_error
code: too_many_requests
message: Muitas requisições. Tente novamente em 42 segundos.
details:
retry_after: 42
provedor:
summary: provider_rate_limited
value:
error:
type: rate_limit_error
code: provider_rate_limited
message: >-
Limite de requisições do provedor atingido. Tente novamente
em instantes.
details: {}
InternalError:
description: |
Erro inesperado do nosso lado. Repita com a mesma
`Idempotency-Key` - ela é o que torna repetir seguro.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
interno:
value:
error:
type: api_error
code: internal_error
message: >-
Erro interno. Se persistir, informe o horário da chamada ao
suporte.
details: {}
ProviderUnavailable:
description: |
O provedor de pagamento não respondeu. **Repita com a mesma
`Idempotency-Key`**: pode ser que a cobrança tenha sido criada lá e
a resposta se perdido no caminho, e a mesma chave devolve a
cobrança em vez de criar outra.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
indisponivel:
value:
error:
type: api_error
code: provider_unavailable
message: >-
O provedor de pagamento não respondeu. Repita a requisição
com a mesma Idempotency-Key.
details: {}
PlatformUnavailable:
description: |
A plataforma não está apta a criar cobranças agora. É problema
nosso: nada que você mude na chamada resolve.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
indisponivel:
value:
error:
type: api_error
code: platform_unavailable
message: >-
A plataforma está temporariamente indisponível para criar
cobranças. Tente novamente em instantes.
details: {}
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: sk_live_… | sk_test_…
description: |
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.
````