POST /v1/charges
Create a charge — card, Pix, or boleto.
Cria uma cobrança. Aceita os métodos card, pix e boleto. Requer os cabeçalhos
Authorization com sua chave secreta (Basic, com a chave como usuário e senha
vazia, ou Bearer <chave>) e Idempotency-Key com uma chave única por intenção
(até 255 caracteres, apenas A-Z a-z 0-9 _ - : .).
Exemplo (curl)
curl -X POST https://api.kirvex.com.br/v1/charges -u "$KIRVEX_SECRET_KEY:" -H "Content-Type: application/json" -H "Idempotency-Key: pedido-1234-pix-1" -d '{
"amount": { "amount": "9990", "currency": "BRL" },
"method": "pix",
"description": "Pedido #1234",
"customer": {
"email": "ada@lovelace.com",
"name": "Ada Lovelace",
"document": "12345678909",
"phone": "+5511987654321",
"address": {
"zipcode": "01310100",
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP"
}
},
"pix": { "expiresInSeconds": 3600 },
"metadata": { "product_id": "prod_...", "offer_id": "poff_..." }
}'
O painel mostra este mesmo exemplo já preenchido com os IDs do seu produto em Produtos → (produto) → Integrações.
Modo de teste: sk_test_ e sk_live_
Existe uma só API, em https://api.kirvex.com.br. É a chave que decide o
modo, não a URL:
sk_live_cobra de verdade.sk_test_nunca move dinheiro real. A cobrança vai para o ambiente de teste (sandbox) do adquirente — Stripe para cartão, Woovi ou Pagar.me para Pix, Pagar.me para boleto, conforme o que estiver configurado na Kirvex.
Uma cobrança de teste volta com "livemode": false. Ela não entra no seu
saldo, não vira saque e não aparece nas vendas, relatórios e exportações do
painel. Os webhooks dela chegam com "livemode": false.
Se o método pedido não tem sandbox configurado, a cobrança é recusada com
422 e o código test_mode_unavailable. Ela nunca é enviada para produção no
lugar. A aba Produtos → (produto) → Integrações do painel mostra, por
método, se o teste está disponível agora.
Cada chave só enxerga os objetos do seu modo: GET, estorno, captura e
cancelamento de uma cobrança real com uma chave sk_test_ respondem 404, e o
mesmo vale ao contrário. As chaves de idempotência também são separadas por
modo.
Operações que só existem com dinheiro real recusam a chave sk_test_ com
test_mode_unavailable: saque (/v1/payouts), antecipação, faturas e saques
em cripto, recebedores, assinaturas e links de pagamento.
O que a cobrança pela API não faz
A cobrança criada por esta rota não gera pedido. Ela não envia o e-mail de
entrega do produto, não libera área de membros e não gera comissão de afiliado
nem rateio de coprodução — isso só acontece em vendas pelo checkout ou pelo link
de pagamento. O valor cobrado é sempre o de amount: a API não lê preço de
produto ou oferta. Para amarrar a cobrança a um produto, mande os IDs em
metadata; a Kirvex guarda e devolve esse campo em GET /v1/charges/{id}. Os
eventos de webhook trazem o charge_id, não o metadata.
Vendas da API na UTMify
Se a UTMify está ligada em Configurações → Rastreamento, cada cobrança real
(sk_live_) criada por esta rota vira um pedido na UTMify, sem nada a mais
para configurar. O pedido usa o id da cobrança e muda de status sozinho:
"aguardando pagamento" quando o Pix ou o boleto é gerado, "pago" quando o
pagamento cai, e "recusado" ou "reembolsado" depois. Cobranças de teste
(sk_test_) não vão, porque a UTMify não grava pedido de teste.
Para a venda aparecer na campanha certa, mande no metadata as UTMs que o
comprador trouxe na URL do seu site:
"metadata": {
"product_id": "prod_...",
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "black-friday",
"utm_content": "video-1",
"utm_term": "curso",
"src": "...",
"sck": "..."
}
- Todas são opcionais. As que não vierem vão vazias para a UTMify.
- O produto do pedido é o de
metadata.product_id, se for um produto seu. Sem ele, a linha leva odescriptionda cobrança. - Mande
customer.name(no boleto, vale oboleto.payerName) para o pedido sair com o nome do comprador. A UTMify exige nome e e-mail: se um deles faltar, a Kirvex manda um identificador da cobrança no lugar ("Cliente A1B2C3" e um e-mail@comprador.kirvex.com.br, que não recebe mensagens). CPF e telefone nunca são inventados: se não vierem, vão vazios.
Pix sem dados do comprador
Para um Pix de um clique no seu site, a cobrança pode ir sem customer e sem
customer_id:
{
"amount": { "amount": "9990", "currency": "BRL" },
"method": "pix",
"description": "Pedido #1234",
"metadata": { "product_id": "prod_...", "utm_source": "facebook" }
}
- Quem paga é identificado pelo próprio banco na hora do pagamento; a Kirvex não inventa nome, CPF nem e-mail no lugar do que não veio.
- Esse Pix vai só para as adquirentes que não exigem dados do pagador. A
Pagar.me exige e-mail, telefone e endereço, então fica de fora. Se a sua conta
só tiver a Pagar.me para Pix, a cobrança é recusada com
503. - Na UTMify, o pedido sai com o identificador da cobrança no lugar do nome e do e-mail (veja a seção acima).
- Cartão e boleto continuam exigindo o comprador.
Request body
{
"amount": { "amount": "9990", "currency": "BRL" },
"method": "pix",
"description": "Pedido #1234",
"customer": {
"email": "ada@lovelace.com",
"name": "Ada Lovelace",
"document": "12345678909",
"phone": "+5511987654321",
"address": {
"zipcode": "01310100",
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"complement": "Conjunto 12"
}
},
"pix": { "expiresInSeconds": 3600 },
"metadata": { "product_id": "prod_...", "offer_id": "poff_..." }
}
- Cartão e boleto:
customeroucustomer_id(um dos dois é obrigatório). Semcustomer_id,customer.emailé obrigatório. - Pix: o comprador é opcional. Dá para mandar só parte dele (o nome, por exemplo) ou nada. Veja "Pix sem dados do comprador" abaixo.
customer.phoneecustomer.address: opcionais, mas a Pagar.me exige os dois (e o e-mail) — veja abaixo.metadata: objeto de texto → texto, opcional. Guardado com a cobrança.pix.expiresInSeconds: de 60 a 86400.
Telefone e endereço do comprador
A Pagar.me exige o telefone e o endereço do comprador em todo pedido: Pix, boleto e cartão. No cartão, o endereço também vai como endereço de cobrança.
- Pix ou boleto sem os dois: a Kirvex manda a cobrança para outra adquirente
configurada. Se a Pagar.me é a única que atende o método, a cobrança volta
503com a mensagemPagar.me requires the buyer's phone and address. - Cartão sem os dois: a cobrança segue para a Pagar.me, que pode recusar.
Se a sua conta usa a Pagar.me, mande sempre customer.phone e customer.address.
| Campo | Formato |
|---|---|
phone | Número brasileiro com DDD. Aceita +5511987654321, 11987654321 ou (11) 98765-4321; a Kirvex converte para +5511987654321 |
address.zipcode | CEP com 8 dígitos. O hífen é aceito e removido (01310-100 → 01310100) |
address.street | Rua, até 200 caracteres |
address.number | Número, até 20 caracteres |
address.neighborhood | Bairro, até 120 caracteres |
address.city | Cidade, até 120 caracteres |
address.state | UF com 2 letras (SP; minúsculas são aceitas) |
address.complement | Opcional, até 120 caracteres |
Telefone ou endereço fora do formato voltam 400 validation_error, com o campo
em param (por exemplo customer.address.zipcode). Um telefone com código de
outro país (+1 …) é recusado.
Com customer_id
O cliente salvo em /v1/customers fornece e-mail, nome,
documento e telefone. Ele não guarda endereço. Por isso, mande o endereço em
customer, junto com o customer_id:
{
"amount": { "amount": "9990", "currency": "BRL" },
"method": "pix",
"customer_id": "cus_...",
"customer": {
"address": {
"zipcode": "01310100",
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP"
}
}
}
Com customer_id, a Kirvex lê só phone e address desse objeto. Um phone
enviado aqui substitui o telefone salvo. E-mail, nome e documento continuam os
do cliente salvo. Um telefone salvo que não seja brasileiro não é enviado à
adquirente.
Response 201
{
"id": "ch_018f1c4b00007abcdef1234567890abc",
"object": "charge",
"status": "pending",
"method": "pix",
"amount": { "amount": "9990", "currency": "BRL" },
"vendor": "woovi",
"vendor_ref": "ch_vnd_xxx",
"created_at": "2026-04-29T12:34:56Z",
"pix": { "qrCode": "00020126..." }
}
Errors
Toda resposta de erro segue o envelope:
{
"error": {
"type": "...",
"code": "...",
"message": "...",
"request_id": "...",
"retryable": false
}
}
Códigos previstos:
validation_erroridempotency_conflictunauthorizedvendor_unavailablecard_declinedkyc_requiredinternal_error
Refund, capture, void
Endpoints relacionados (todos requerem Idempotency-Key):
POST /v1/charges/{id}/refund— full ou partial refund. Aceitaamountopcional no body. Boleto exigebuyer_pix_keye é devolvido por Pix ao comprador, saindo do seu saldo (veja Refunds).POST /v1/charges/{id}/capture— captura explícita para cards em modomanualcapture.POST /v1/charges/{id}/void— cancela uma cobrança autorizada (não capturada).
OpenAPI
A spec completa está em /openapi.json.