curl --request GET \
--url https://api.usevext.com/v1/charges/{code} \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usevext.com/v1/charges/{code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usevext.com/v1/charges/{code}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.usevext.com/v1/charges/{code}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "charge",
"id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
"status": "paid",
"payment_method": "pix",
"amount": 10000,
"currency": "BRL",
"platform_fee": 798,
"net_amount": 9103,
"refunded_amount": 0,
"description": "Curso de Vue 3",
"reference": "pedido-1042",
"metadata": {
"carrinho": "cart_88f21",
"campanha": "black-friday"
},
"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_to_end_id": "E12345678202608041200"
},
"created_at": "2026-08-04T14:00:00+00:00",
"paid_at": "2026-08-04T14:03:11+00:00",
"expired_at": null,
"refunded_at": null
}Consultar cobrança
Busca uma cobrança pelo código público ch_….
curl --request GET \
--url https://api.usevext.com/v1/charges/{code} \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usevext.com/v1/charges/{code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usevext.com/v1/charges/{code}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.usevext.com/v1/charges/{code}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"object": "charge",
"id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
"status": "paid",
"payment_method": "pix",
"amount": 10000,
"currency": "BRL",
"platform_fee": 798,
"net_amount": 9103,
"refunded_amount": 0,
"description": "Curso de Vue 3",
"reference": "pedido-1042",
"metadata": {
"carrinho": "cart_88f21",
"campanha": "black-friday"
},
"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_to_end_id": "E12345678202608041200"
},
"created_at": "2026-08-04T14:00:00+00:00",
"paid_at": "2026-08-04T14:03:11+00:00",
"expired_at": null,
"refunded_at": null
}404 não distingue “não existe” de “existe, mas é de outra conta”. Responder a diferença
confirmaria a existência de cobranças alheias a quem tentasse adivinhar códigos.Authorizations
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.
Scopes
Path Parameters
Código público da cobrança, no formato ch_….
^ch_[0-9a-z]{26}$Response
A cobrança.
Uma cobrança, como a API a devolve. Todo campo desta lista está
sempre presente - os anuláveis vêm com null, nunca ausentes.
Marcar como opcional o que nunca falta obrigaria você a testar a
existência de uma chave que sempre existe.
Nos webhooks há uma exceção documentada: veja ChargeMinimal.
"charge"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.
"ch_01k1y6r6m6q2x0p3d9v4t7c8n2"
Situação da cobrança. Só os estados de trânsito - pending,
processing e in_analysis - ainda mudam sozinhos; os demais são
terminais, exceto os que ainda admitem estorno.
processing e in_analysis são do cartão: a autorização é
decidida na mesma requisição, mas pode parar na análise de fraude
antes de virar paid ou failed. No PIX a cobrança vai direto de
pending para o desfecho.
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.
chargedback é definitivo: o dinheiro voltou pelo caminho da
bandeira, e nem cancelamento nem estorno são mais possíveis.
pending, processing, in_analysis, paid, expired, canceled, partially_refunded, refunded, failed, chargedback O meio pelo qual esta cobrança foi criada. Omitir o campo na
criação continua significando pix - é o que toda integração
que existe hoje espera, e mudar isso as quebraria todas de uma
vez.
pix, credit_card, boleto O que o comprador paga, em centavos inteiros.
Cuidado com a assimetria, porque ela é a pegadinha desta API: no
POST você manda o PREÇO DO PRODUTO, e aqui volta o TOTAL. No
Pix e no cartão à vista os dois são iguais; no cartão parcelado
este é maior, porque inclui o juro que o comprador pagou.
O preço do produto, de volta, é amount - interest.
"BRL"Nossa taxa, em centavos inteiros. Congelada na criação: reflete o contrato que valia quando a venda aconteceu, não o de hoje.
Ela incide sobre o preço do produto (amount - interest), e
não sobre o total pago. É o que faz parcelar não custar nada a
você - ver net_amount.
O que fica com o vendedor, em centavos inteiros.
Não é amount - platform_fee. Essa conta dá um número maior,
e a diferença é o JURO do parcelamento: ele está dentro do
amount porque o comprador o pagou, mas não é receita de
ninguém aqui - atravessa até o arranjo de pagamento.
A identidade que fecha, e que o banco confere em toda cobrança:
amount = net_amount + platform_fee + interest + co-produção
No Pix e no cartão à vista o juro é zero, e aí
amount - platform_fee fecha.
Total já devolvido ao comprador, em centavos inteiros. Acumulado entre estornos parciais.
O que você enviou na criação. Sempre um objeto, {} quando
não houve nada - nunca null, para o seu código não ter dois
casos a tratar.
Show child attributes
Show child attributes
{
"carrinho": "cart_88f21",
"campanha": "black-friday"
}
null na cobrança que não tem comprador vinculado. A chave em
si nunca falta.
Show child attributes
Show child attributes
Presente em toda cobrança, inclusive nas de cartão - onde os
três campos vêm null. Um objeto sempre presente evita o
if (charge.pix) antes de cada leitura.
Show child attributes
Show child attributes
Presente em toda cobrança, inclusive nas de PIX - onde os campos
vêm null. Mesma regra do pix acima, e pelo mesmo motivo.
O que não está aqui, e não vai estar: os seis primeiros
dígitos, o código de retorno da adquirente e a nota do
antifraude. Os dois primeiros são diagnóstico nosso; a nota numa
resposta pública seria um oráculo de risco para quem testa
cartão em lote. O código de recusa sai numa recusa, em
error.details.decline_code, onde quem lê é o seu servidor.
Show child attributes
Show child attributes
Presente em toda cobrança, inclusive nas de PIX e de cartão -
onde os campos vêm null. Mesma regra do pix e do card, e
pelo mesmo motivo.
Boleto é oferecido apenas a lojas em conta de split na Pagar.me.
Numa loja fora desse arranjo, POST /v1/charges com
payment_method: boleto responde 422 com
boleto_not_available.
Show child attributes
Show child attributes