Uma API pra todos os gateways
Você conecta seus gateways no painel e integra só com a gente. Toda cobrança, resposta, erro e webhook tem o mesmo formato, não importa se passou pelo Mercado Pago, PagBank, Stripe, Pagar.me, Asaas ou Woovi.
Valores sempre em centavos (inteiro): 4990 = R$ 49,90. Datas em ISO 8601. Corpo e resposta em JSON.
# Endereço base
{{BASE}}/v1Autenticação
Mande a chave secreta no cabeçalho Authorization. Crie as chaves no painel, em Chaves e webhook.
AuthorizationobrigatórioBearer sk_live_… (produção) ou Bearer sk_test_… (sandbox)Idempotency-KeyrecomendadoUm id seu por cobrança (ex.: o número do pedido). Repetir a chamada com a mesma chave devolve a mesma cobrança e nunca cobra duas vezes.curl {{BASE}}/v1/gateways \
-H "Authorization: Bearer sk_test_..."Sandbox
Com uma chave sk_test_, as cobranças vão pro ambiente de teste de cada gateway, usando as conexões que você cadastrou como Sandbox no painel. Nada é cobrado de verdade.
No painel, a tela Testar cobrança gera um Pix ou boleto de teste e mostra a resposta exata da API.
A chave de produção funciona com a assinatura ativa. A de sandbox funciona sempre.
sk_test_… → conexões "Sandbox" sk_live_… → conexões "Produção"
Escolher o gateway
Três jeitos, e dá pra misturar:
Automático – mande "gateway": "auto" (ou não mande). Valem as regras de Roteamento do painel: o gateway principal de cada método e o fallback. O dono da loja muda as regras sem mexer no código.
Fixo – mande o id do gateway, ex.: "gateway": "mercadopago". Só ele é tentado.
O comprador escolhe – mostre botões na sua tela (Mercado Pago, Woovi…) e mande o id do que ele clicou.
{ "valor": 4990, "metodo": "pix", "gateway": "auto" }
{ "valor": 4990, "metodo": "pix", "gateway": "woovi" }Criar cobrança
Cria uma cobrança de Pix, boleto ou cartão.
valorinteiro, obrigatórioEm centavos, mínimo 100metodopix | boleto | cartaoForma de pagamentogatewaytexto, padrão autoauto ou o id do gatewaydescricaotextoAparece pro comprador quando o gateway mostraclienteobjetonome, email, documento (CPF/CNPJ), telefone e, pra boleto no Mercado Pago, endereco { cep, rua, numero, bairro, cidade, uf }. O que cada gateway exige está na tabela de gateways.cartaoobjeto, só cartãotoken gerado no navegador pelo SDK do gateway escolhido (veja a tabela abaixo), parcelas; no Mercado Pago também bandeira (ex.: visa) e emissor_id. Como o token é de um gateway só, cartão sempre vai com gateway fixo. Mande também retorno (URL): se o banco pedir 3D Secure, a resposta vem pendente com autenticacao_url pra mandar o comprador, e ele volta pro retorno.pix_expira_em_minutosinteiro, padrão 60De 15 a 10080boleto_vence_em_diasinteiro, padrão 3De 1 a 60metadataobjetoSeus dados (ex.: id do pedido). Volta igual na consulta e no webhook. Até 4 KB.Resposta 201 com a cobrança. Em tentativas aparece cada gateway tentado (útil pra ver quando o fallback entrou).
const r = await fetch("{{BASE}}/v1/cobrancas", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.TPH_CHAVE,
"Content-Type": "application/json",
"Idempotency-Key": "pedido-1042"
},
body: JSON.stringify({
valor: 4990,
metodo: "pix",
gateway: "auto",
cliente: { nome: "Ana Souza", documento: "52998224725", email: "ana@email.com" },
metadata: { pedido: "1042" }
})
});
const cobranca = await r.json();
// cobranca.pix.copia_e_cola → mostrar pro comprador
$ch = curl_init("{{BASE}}/v1/cobrancas");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("TPH_CHAVE"),
"Content-Type: application/json",
"Idempotency-Key: pedido-1042",
],
CURLOPT_POSTFIELDS => json_encode([
"valor" => 4990, "metodo" => "pix", "gateway" => "auto",
"cliente" => ["nome" => "Ana Souza", "documento" => "52998224725"],
"metadata" => ["pedido" => "1042"],
]),
]);
$cobranca = json_decode(curl_exec($ch), true);
curl {{BASE}}/v1/cobrancas \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1042" \
-d '{"valor":4990,"metodo":"pix","gateway":"auto",
"cliente":{"nome":"Ana Souza","documento":"52998224725"}}'{
"id": "ch_9KdP2xQm4Lw8Tz1B",
"status": "pendente",
"valor": 4990,
"metodo": "pix",
"gateway": "asaas",
"gateway_pedido": "auto",
"ambiente": "producao",
"estornado": 0,
"pix": {
"copia_e_cola": "00020126...",
"qr_code_base64": "iVBORw0KGgo...",
"expira_em": "2026-11-09T21:30:00-03:00"
},
"metadata": { "pedido": "1042" },
"criada_em": "2026-11-09T20:30:00.000Z",
"paga_em": null,
"tentativas": [
{ "gateway": "asaas", "resultado": "ok", "latencia_ms": 412 }
]
}Consultar cobrança
Devolve o estado atual e as tentativas. Status possíveis: pendente, paga, falhou, expirada, cancelada, estornada, estornada_parcial.
Não precisa ficar consultando: o webhook avisa quando muda. Mesmo se um webhook do gateway se perder, a gente reconsulta as pendentes sozinho.
curl {{BASE}}/v1/cobrancas/ch_9KdP2xQm4Lw8Tz1B \
-H "Authorization: Bearer sk_live_..."Listar cobranças
limite1 a 100, padrão 20statusopcionalFiltra por statusantes_deidPra paginar: passe o id da última cobrança recebida{ "dados": [ … ], "tem_mais": true }Estornar
Estorno total (sem valor) ou parcial (valor em centavos). A gente chama o gateway que processou a cobrança, você não precisa saber qual foi.
curl -X POST {{BASE}}/v1/cobrancas/ch_9KdP2x.../estorno \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"valor":1000}'
→ { "status": "estornada_parcial", "estornado": 1000, … }Cartão por redirecionamento
Pra cartão sem montar formulário: mande "modo": "redirect" e um retorno. A resposta traz checkout_url: mande o comprador pra lá. Ele paga na página do gateway (com parcelas) e volta pro seu retorno. O webhook cobranca.paga chega como sempre.
modo"redirect"Só com metodo: "cartao"retornoURL, obrigatórioPra onde o comprador volta. Pode usar {cobranca}, que trocamos pelo id.parcelas_max1 a 12Até quantas parcelas o gateway ofereceGateways com página de pagamento: Mercado Pago (Checkout Pro), Stripe (Checkout) e InfinitePay (Checkout, com Pix também). Com gateway: "auto", se o principal estiver fora do ar a página é criada no fallback.
curl {{BASE}}/v1/cobrancas \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"valor":14990,"metodo":"cartao","modo":"redirect",
"parcelas_max":3,
"retorno":"https://sualoja.com/pedido/1042?c={cobranca}",
"cliente":{"email":"ana@email.com"}}'
→ { "id": "ch_…", "status": "pendente", "modo": "redirect",
"checkout_url": "https://www.mercadopago.com.br/checkout/…" }Checkout transparente
O formulário de pagamento aparece dentro da sua página: Pix com QR, boleto e cartão com parcelas, sem o comprador sair do seu site. São três passos:
1. Seu servidor cria uma sessão de checkout com o valor (assim ninguém altera o preço pelo navegador).
2. Sua página carrega o checkout.js e monta o formulário com o id da sessão.
3. Quando o pagamento sai, você recebe o webhook cobranca.paga com o sessao_id e a sua metadata.
Cartão: o número vira token no navegador com o SDK oficial do gateway (Mercado Pago, Stripe, Pagar.me ou PagBank) e a chave pública da sua conta, cadastrada no painel em Formas de pagamento (no PagBank ela é gerada sozinha). O número do cartão não passa pelo seu site nem pelo seu servidor. Sem chave pública, o cartão abre a página segura do gateway e volta.
Com mais de um gateway pronto, o cartão vai pro principal do cartão em Roteamento. Se o banco pedir autenticação (3D Secure), o comprador confirma no banco e volta pra página de pagamento.
sessaotexto, obrigatórioO id (se_…) que o seu servidor recebeuaoPagar(r)funçãoChamada quando a cobrança é paga: { sessao, cobranca, metodo }. Sem ela, o comprador vai pro retorno da sessão.aoCarregar(r)funçãoFormulário pronto: { sessao, situacao }alturaInicialpx, padrão 420Depois a altura acompanha o conteúdo sozinhaImportante: aoPagar serve pra mostrar o "obrigado". Pra liberar o pedido, confie no webhook ou consulte GET /v1/checkout/sessoes/:id no seu servidor.
<div id="pagamento"></div>
<script src="{{BASE}}/checkout.js"></script>
<script>
TrendPayHub.montar("#pagamento", {
sessao: "se_…", // criada no seu servidor
aoPagar: function (r) {
location.href = "/obrigado?pedido=1042";
}
});
</script>Sessões de checkout
Uma sessão é um pagamento de uso único com valor travado. Crie no seu servidor, com a chave secreta, e mande só o id pra página. Também dá pra mandar o comprador direto pra url (página completa, sem embutir).
valorcentavos, obrigatóriodescricaotextoPadrão "Pagamento"metodoslistaPadrão ["pix","cartao","boleto"]gatewayauto ou idPadrão auto (roteamento). Também aceita gateway_modo como nos links, inclusive comprador.parcelas_max1 a 12clienteobjetonome, email, documento: já vêm preenchidos pro compradormetadataobjetoEx.: {"pedido":"1042"}. Vai em todas as cobranças e webhooks da sessão.retornoURLPra onde o comprador vai depois de pagar (página completa ou sem aoPagar). Aceita {cobranca} e {sessao}.origenslistaSites que podem embutir a sessão, ex.: ["https://sualoja.com"]. Sem ela, qualquer site.expira_em_minutos5 a 10080, padrão 60cor#RRGGBBCor do botãostatus: aberta, paga, expirada ou cancelada. GET /v1/checkout/sessoes/:id devolve a sessão com as cobranças dela. POST /v1/checkout/sessoes/:id/cancelar fecha uma sessão que não foi paga.
curl {{BASE}}/v1/checkout/sessoes \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"valor":14990,"descricao":"Pedido #1042",
"metodos":["pix","cartao"],"parcelas_max":3,
"metadata":{"pedido":"1042"},
"origens":["https://sualoja.com"]}'
→ { "id": "se_…", "url": "{{BASE}}/pagar/se_…",
"status": "aberta", "valor": 14990,
"expira_em": "…", "cobrancas": [] }
# webhook quando pagar
{ "tipo": "cobranca.paga",
"dados": { "id": "ch_…", "status": "paga",
"sessao_id": "se_…",
"metadata": { "pedido": "1042" } } }Links de pagamento
Um endereço pronto pra mandar no WhatsApp, Instagram ou e-mail. O comprador abre no celular, escolhe Pix, boleto ou cartão e paga numa página com a marca da sua loja. Também dá pra criar pelo painel, em Checkout e links.
descricaotexto, obrigatórioO que está sendo vendidovalorcentavos, obrigatóriometodoslistaPadrão ["pix","cartao","boleto"]. Só aparecem os que seus gateways conectados aceitam.gateway_modoauto | fixo | compradorQuem escolhe o gateway. Com fixo, mande gateway_fixo; com comprador, gateways_comprador (2 ou mais).usounico | multiploÚnico fecha depois do primeiro pagamentoparcelas_max · cor · expira_emopcionaisPagamentos do link geram as mesmas cobranças e webhooks, com link_id e metadata.link preenchidos. GET /v1/links lista os seus.
curl {{BASE}}/v1/links \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"descricao":"Tênis Corrida X","valor":14990,
"metodos":["pix","cartao"],"uso":"unico"}'
→ { "id": "lk_…", "url": "{{BASE}}/pagar/lk_…", "situacao": "aberto" }Webhooks
Cadastre uma URL no painel. Enviamos um POST com JSON a cada mudança. Responda 2xx em até 10 segundos; se falhar, tentamos de novo por até 3 dias (1 min, 5 min, 15 min, 1 h…).
cobranca.pendenteCriada, esperando o pagamentocobranca.pagaPagamento confirmado: libere o pedido aquicobranca.falhouRecusada ou nenhum gateway conseguiu processarcobranca.expiradaPix ou boleto venceu sem pagamentocobranca.estornadaEstorno total ou parcialConfira a assinatura. O cabeçalho X-Assinatura vem como t=<unix>,v1=<hmac>, onde hmac = HMAC-SHA256(segredo, t + "." + corpo_bruto). O segredo está no painel. Recuse se a diferença de tempo passar de 5 minutos.
O mesmo evento pode chegar mais de uma vez: use o id do evento (cabeçalho X-Evento-Id) pra não processar duas vezes.
import crypto from "node:crypto";
// Use o corpo BRUTO (texto), antes do JSON.parse
app.post("/webhooks/pagamentos", express.text({ type: "*/*" }), (req, res) => {
const partes = Object.fromEntries(req.get("X-Assinatura").split(",").map(p => p.split("=")));
const esperado = crypto.createHmac("sha256", process.env.TPH_WEBHOOK_SEGREDO)
.update(partes.t + "." + req.body).digest("hex");
const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
if (!recente || !crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1))) {
return res.sendStatus(401);
}
const evento = JSON.parse(req.body);
if (evento.tipo === "cobranca.paga") liberarPedido(evento.dados.metadata.pedido);
res.sendStatus(200);
});
$corpo = file_get_contents("php://input");
parse_str(str_replace(",", "&", $_SERVER["HTTP_X_ASSINATURA"]), $p);
$esperado = hash_hmac("sha256", $p["t"] . "." . $corpo, getenv("TPH_WEBHOOK_SEGREDO"));
if (abs(time() - (int)$p["t"]) > 300 || !hash_equals($esperado, $p["v1"])) {
http_response_code(401); exit;
}
$evento = json_decode($corpo, true);
if ($evento["tipo"] === "cobranca.paga") liberarPedido($evento["dados"]["metadata"]["pedido"]);
http_response_code(200);{
"id": "ev_7Hq2Lm9TzR4vW8nB",
"tipo": "cobranca.paga",
"criado_em": "2026-11-09T20:31:02.000Z",
"dados": {
"id": "ch_9KdP2xQm4Lw8Tz1B",
"status": "paga",
"valor": 4990,
"gateway": "asaas",
"metadata": { "pedido": "1042" }
}
}Erros
Todo erro vem no mesmo formato. Quando o gateway recusou, mandamos também o código original dele em original.
dados_invalidos422Algum campo errado; veja campocartao_recusado · saldo_insuficiente · risco_alto402Recusa do emissorgateway_indisponivel503Nenhum gateway da regra respondeu (o fallback já foi tentado)gateway_nao_conectado400Conecte o gateway no painel, no ambiente certoassinatura_inativa402Chave de produção com a assinatura pendentelimite_plano429Limite de transações do mês atingidonao_autorizado401Chave ausente, inválida ou revogadalimite_requisicoes429Mais de 300 requisições por minutoHTTP 402
{
"erro": {
"codigo": "saldo_insuficiente",
"mensagem": "Pagamento recusado pelo emissor",
"cobranca_id": "ch_…",
"gateway": "mercadopago",
"original": { "codigo": "cc_rejected_insufficient_amount" }
}
}Gateways suportados
Use o id pra forçar um gateway. Gateways novos entram sem mudar sua integração. A rota devolve só os conectados na sua conta, com a saúde de agora.
| Gateway | id | Métodos |
|---|---|---|
| Mercado Pago | mercadopago | Pix, boleto, cartão |
| PagBank (PagSeguro) | pagbank | Pix, boleto, cartão |
| Stripe | stripe | Pix, boleto, cartão |
| Pagar.me | pagarme | Pix, boleto, cartão |
| Asaas | asaas | Pix, boleto |
| Woovi (OpenPix) | woovi | Pix |
| Cielo | cielo | Pix, boleto, cartão |
| Rede (Itaú) | rede | Pix (cartão em breve) |
| Getnet (Santander) | getnet | Pix, boleto (cartão em breve) |
| InfinitePay | infinitepay | Cartão (e Pix) na página da InfinitePay: só modo: "redirect", só produção |
| Pix direto · Banco do Brasil | pix_bb | Pix |
| Pix direto · Inter Empresas | pix_inter | Pix |
| Pix direto · Sicoob | pix_sicoob | Pix (só produção) |
| Pix direto · Efí | pix_efi | Pix |
| Pix direto · Itaú | pix_itau | Pix |
| Pix direto · Bradesco | pix_bradesco | Pix |
| Pix direto · Santander | pix_santander | Pix (teste na pré-produção do Santander) |
| Pix direto · C6 Bank | pix_c6 | Pix |
Pix direto do banco: o QR é gerado pela API Pix do seu banco (padrão do Banco Central) e o dinheiro cai na conta PJ. O banco exige o certificado digital da API Pix (enviado no painel, guardado criptografado). A confirmação é por consulta ao banco: a cada poucos segundos enquanto o comprador está na página, e a cada minuto depois, porque o aviso de Pix dos bancos exige certificado no servidor que recebe. Na Efí o aviso é cadastrado sozinho. Devolução pelo /estorno normal. Bancos: Banco do Brasil, Inter, Sicoob, Efí, Itaú, Bradesco, Santander e C6.
InfinitePay: a API dela só cria link de pagamento, então use metodo: "cartao" com modo: "redirect". O comprador escolhe cartão (até 12x) ou Pix na página da InfinitePay. O pagamento é confirmado na InfinitePay a partir do aviso (que é automático). Sem ambiente de teste e sem estorno pela API (só pelo app).
O que cada gateway exige do comprador e como gerar o token do cartão (no checkout transparente isso já é feito por nós):
| Gateway | Pix | Boleto | Token do cartão |
|---|---|---|---|
| Mercado Pago | nome, e-mail, CPF/CNPJ, endereço | MercadoPago.js (token + bandeira) · Public Key | |
| PagBank | nome, e-mail, CPF/CNPJ | + endereço | SDK PagBank (card.encrypted) · chave gerada sozinha |
| Stripe | nome e e-mail | nome, e-mail, CPF/CNPJ, endereço | Stripe.js (pm_…) · chave publicável |
| Pagar.me | nome, e-mail, CPF/CNPJ (telefone recomendado) | + endereço | API de tokens (token_…) · chave pública + domínio liberado |
| Asaas | nome e CPF/CNPJ | nome e CPF/CNPJ | — |
| Woovi | nada obrigatório | — | — |
| Cielo | nada obrigatório (nome e CPF/CNPJ recomendados) | nome, CPF/CNPJ, endereço (boleto contratado na Cielo) | Silent Order Post (PaymentToken) · Client ID e Client Secret |
| Rede | nada obrigatório | — | — (em breve) |
| Getnet | nada obrigatório · QR vale até 30 min | nome, CPF/CNPJ, endereço | — (em breve) |
| Pix direto (bancos) | nada obrigatório (com nome + CPF/CNPJ, o banco mostra o pagador) | — | — |
Avisos de pagamento: na Cielo, cadastre a URL que o painel mostra em URL de notificações; na Rede, peça pra central cadastrar (opcional, o Pix é conferido a cada minuto). A Getnet não tem consulta de status: o pagamento só é confirmado pela notificação, então peça pro atendimento da Getnet cadastrar a URL do painel como notificação de Pix e de boleto.
Cartão na Rede e na Getnet depende da certificação PCI da plataforma, porque nelas o número do cartão passa pelo servidor.
[
{ "id": "mercadopago", "nome": "Mercado Pago", "metodos": ["pix","boleto","cartao"], "saude": "operacional" },
{ "id": "asaas", "nome": "Asaas", "metodos": ["pix","boleto"], "saude": "operacional" }
]