Comece aqui
Documentação da API SummitPay
Infraestrutura de pagamentos simples, rápida e poderosa para desenvolvedores.
Nesta documentação você encontra tudo para integrar a API SummitPay: autenticação, PIX, cartão, boleto, cripto, saques e webhooks — com exemplos prontos para copiar.
O que é a SummitPay?
A SummitPay é um gateway de pagamento brasileiro que nasceu da nossa própria necessidade de simplificar cobranças em produtos digitais. Percebemos que as soluções existentes eram desnecessariamente complexas:
- Documentações extensas e confusas
- Processos de homologação longos e burocráticos
- Múltiplas formas de realizar a mesma operação
- Cobranças abusivas e taxas escondidas
Nossa solução transforma a complexidade das Fintechs tradicionais em uma API simples, direta e poderosa — com suporte a PIX, Cartão de Crédito, Boleto e Cripto em um único endpoint.
// Gerar um Pix em menos de 10 linhas
const response = await fetch('https://usesummitpay.com/api/v1/gateway/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
'api-key': 'SUA_CHAVE_AQUI',
amount: 150.00,
method: 'pix',
client: { name: 'João Silva', document: '12345678900', email: 'joao@email.com' }
})
});
const { paymentCode, idTransaction } = await response.json();
// Pronto. paymentCode = o Pix Copia e Cola.
// Gerar um Pix em menos de 10 linhas
$payload = json_encode([
'api-key' => 'SUA_CHAVE_AQUI',
'amount' => 150.00,
'method' => 'pix',
'client' => ['name' => 'João Silva', 'document' => '12345678900', 'email' => 'joao@email.com']
]);
$ch = curl_init('https://usesummitpay.com/api/v1/gateway/');
curl_setopt_array($ch, [CURLOPT_POST => 1, CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true]);
$data = json_decode(curl_exec($ch), true);
// $data['paymentCode'] = o Pix Copia e Cola
Autenticação
Todas as requisições de pagamento exigem o parâmetro api-key no corpo JSON.
Você encontra sua chave no painel em Configurações → API Keys.
api-key no front-end. Sempre envie requisições pelo seu servidor
back-end.
1. PIX — Gerar Cobrança
Crie cobranças Pix dinâmicas com suporte a Split, webhook e rastreamento UTM.
Parâmetros do Corpo
| Campo | Tipo | Req? | Descrição |
|---|---|---|---|
api-key |
string | obrig. | Sua chave de API |
amount |
float | obrig. | Valor em BRL (ex: 100.50) |
method |
string | opc. | Use "pix" ou omita (padrão é pix) |
client.name |
string | obrig. | Nome completo do pagador |
client.document |
string | obrig. | CPF (11 dígitos) ou CNPJ (14 dígitos), somente números |
client.email |
string | obrig. | E-mail do pagador |
external_reference |
string | opc. | Seu ID interno do pedido |
notification_url |
string | opc. | URL para receber o webhook de confirmação |
split.percentual |
float | opc. | % a repassar para outro usuário (ex: 10) |
split.destino |
string | opc. | user_id ou id do usuário que recebe o split |
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 100.50,
"method": "pix",
"external_reference": "pedido_123",
"notification_url": "https://seu-site.com/webhook",
"client": {
"name": "João Silva",
"document": "12345678900",
"email": "joao@email.com",
"phone": "11999999999"
},
"split": {
"percentual": 10,
"destino": "id_do_parceiro"
}
}
$payload = [
'api-key' => 'SUA_CHAVE_AQUI',
'amount' => 100.50,
'method' => 'pix',
'external_reference' => 'pedido_123',
'notification_url' => 'https://seu-site.com/webhook',
'client' => [
'name' => 'João Silva',
'document' => '12345678900',
'email' => 'joao@email.com',
],
];
$ch = curl_init('https://usesummitpay.com/api/v1/gateway/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
echo $data['paymentCode']; // Copia e cola do PIX
const axios = require('axios');
const { data } = await axios.post(
'https://usesummitpay.com/api/v1/gateway/',
{
'api-key': 'SUA_CHAVE_AQUI',
amount: 100.50, method: 'pix',
client: { name: 'João Silva', document: '12345678900', email: 'joao@email.com' }
}
);
console.log(data.paymentCode); // Pix Copia e Cola
{
"status": "WAITING_FOR_APPROVAL",
"idTransaction": "abc123-def456-...",
"paymentCode": "00020101021126580014br.gov.bcb.pix...",
"paymentCodeBase64": "iVBORw0KGgo...",
"expiresAt": "2026-01-01 15:30:00"
}
2. Cartão de Crédito
Cobranças com cartão de crédito. Bandeiras suportadas: Visa, Mastercard, Elo, Hipercard, Amex e Diners. Parcelamento em até 12x com tabela de juros progressiva.
card
no payload. Não é necessário enviar "method": "credit_card".
Parâmetros Adicionais (Cartão)
| Campo | Tipo | Req? | Descrição |
|---|---|---|---|
card.number |
string | obrig. | Número do cartão (somente dígitos, validado pelo algoritmo de Luhn) |
card.holder_name |
string | obrig. | Nome do titular como no cartão |
card.expiry_month |
string | obrig. | Mês de validade (ex: "07") |
card.expiry_year |
string | obrig. | Ano de validade com 2 ou 4 dígitos (ex: "27" ou "2027") |
card.cvv |
string | obrig. | CVV / CVC (3 ou 4 dígitos) |
installments |
int | opc. | Parcelas (1–12). 1–3 sem juros; 4+ com juros progressivos. Padrão: 1 |
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 299.90,
"installments": 3,
"client": {
"name": "Maria Souza",
"document": "98765432100",
"email": "maria@email.com"
},
"card": {
"number": "4111111111111111",
"holder_name": "MARIA P SOUZA",
"expiry_month": "12",
"expiry_year": "27",
"cvv": "123"
},
"external_reference": "pedido_456"
}
{
"status": "PAID_OUT",
"status_normalized": "PAID_OUT",
"idTransaction": "tx_card_abc123",
"paymentCode": "",
"card_brand": "visa",
"installment_info": {
"installments": 3,
"installment_value": 99.97,
"total_with_fee": 299.90,
"monthly_rate": 0,
"has_fee": false
}
}
{
"status": "DECLINED",
"status_normalized": "DECLINED",
"idTransaction": "tx_card_xyz789",
"message": "Transação não autorizada pela operadora",
"decline_reason": "insufficient_funds"
}
Tabela de Juros por Parcelas
| Parcelas | Taxa Mensal | Observação |
|---|---|---|
| 1x, 2x, 3x | 0% | Sem juros |
| 4x, 5x, 6x | 1,99% a.m. | — |
| 7x, 8x, 9x | 2,49% a.m. | — |
| 10x, 11x, 12x | 2,99% a.m. | — |
3. Boleto Bancário
Gere boletos bancários com vencimento configurável. Confirmação em até 2 dias úteis após o pagamento.
client.address (obrigatório por regulamentação
bancária).
Parâmetros Adicionais (Boleto)
| Campo | Tipo | Req? | Descrição |
|---|---|---|---|
method |
string | obrig. | Deve ser "boleto" |
due_date |
string | opc. | Data de vencimento YYYY-MM-DD. Padrão: 3 dias úteis |
boleto_instructions |
string | opc. | Instrução impressa no boleto |
client.address.street |
string | obrig. | Logradouro |
client.address.number |
string | obrig. | Número |
client.address.city |
string | obrig. | Cidade |
client.address.state |
string | obrig. | UF (2 letras) |
client.address.zipcode |
string | obrig. | CEP (8 dígitos) |
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 79.90,
"method": "boleto",
"due_date": "2026-02-28",
"boleto_instructions": "Não receber após o vencimento.",
"client": {
"name": "Carlos Oliveira",
"document": "11122233344",
"email": "carlos@email.com",
"address": {
"street": "Rua das Flores",
"number": "123",
"city": "São Paulo",
"state": "SP",
"zipcode": "01310100"
}
}
}
{
"status": "WAITING_FOR_APPROVAL",
"status_normalized": "WAITING_FOR_APPROVAL",
"idTransaction": "tx_boleto_abc123",
"paymentCode": "03399.26290 64000.000004 00040.901018 9 96340000007990",
"barcode": "03399.26290 64000.000004 00040.901018 9 96340000007990",
"paymentUrl": "https://boleto.adquirente.com.br/abc123.pdf",
"due_date": "2026-02-28",
"instructions": "Não receber após o vencimento."
}
4. Pagamentos Cripto
Aceite pagamentos em criptomoedas com conversão automática do BRL para a moeda escolhida via cotação em tempo real (CoinGecko).
Moedas e Redes Suportadas
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 150.00,
"currency": "usdt",
"network": "trc20",
"external_reference": "pedido_789",
"notification_url": "https://seu-site.com/webhook/crypto",
"client": {
"name": "Ana Costa",
"email": "ana@email.com",
"document": "55566677788"
}
}
{
"status": "ok",
"idTransaction": "pay_abc123",
"payment_method": "crypto",
"provider": "nowpayments",
"currency": "USDT",
"network": "trc20",
"network_label": "TRON (TRC20)",
"amount_brl": 150.00,
"amount_crypto": 28.64,
"wallet_address": "TQPnMF9hqzqVHkMgBvgFGAKWHfsMsG8XvT",
"qr_code_url": "https://chart.googleapis.com/chart?...",
"expires_at": "2026-01-01 14:50:00",
"timeout_minutes": 20,
"exchange_rate": {
"price_brl": 5.24,
"price_usd": 1.00,
"change_24h": 0.01
}
}
# Cotações em tempo real (sem autenticação)
GET /api/v1/crypto/?action=rates
# Simular conversão
GET /api/v1/crypto/?action=convert&amount=150¤cy=usdt&network=trc20
# Consultar status de uma cobrança
GET /api/v1/crypto/?action=status&idTransaction=pay_abc123
# Listar moedas e redes disponíveis
GET /api/v1/crypto/?action=supported
5. Saque (Cash-out)
Solicite transferências via Pix do saldo da sua conta SummitPay para uma chave externa. Suporte completo a todos os tipos de chave Pix.
api-key no front-end. Sempre envie requisições pelo seu servidor back-end.
Parâmetros do Corpo
| Campo | Tipo | Req? | Descrição |
|---|---|---|---|
api-key |
string | obrig. | Sua chave de API (painel → Configurações → API Keys) |
amount |
float | obrig. | Valor do saque em BRL (ex: 100.50). Esse valor é debitado do seu saldo |
name |
string | obrig. | Nome completo do favorecido |
cpf |
string | obrig. | CPF ou CNPJ do favorecido — somente números (11 ou 14 dígitos) |
keypix |
string | obrig.* | Valor da chave Pix de destino |
tipo_chave |
string | opc. | Tipo da chave Pix. Padrão: CPF |
tipo_chave for CPF e você omitir keypix, a API usa o valor de cpf como chave.
Tipos de Chave Pix (tipo_chave)
| Valor | Descrição | Formato de keypix |
Exemplo |
|---|---|---|---|
CPF |
Chave vinculada a CPF | 11 dígitos (com ou sem máscara) | 12345678900 |
CNPJ |
Chave vinculada a CNPJ | 14 dígitos (com ou sem máscara) | 12345678000199 |
EMAIL |
E-mail cadastrado no Pix | E-mail válido | favorecido@email.com |
PHONE |
Telefone cadastrado no Pix | DDD + número, com ou sem +55 |
11999998888 ou +5511999998888 |
EVP |
Chave aleatória (UUID) | UUID gerado pelo banco | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
Aliases aceitos
E-MAIL → EMAIL
TELEFONE, CELULAR → PHONE
ALEATORIA, CHAVE_ALEATORIA, RANDOM → EVP
Taxas, saldo e limites
amount é o valor bruto debitado da sua conta.
A taxa de saque (fixa ou percentual, conforme sua conta) é descontada antes do envio Pix.
O favorecido recebe o valor líquido (amount − taxa).
- Saldo necessário: disponível ≥
amount - Valor mínimo: R$ 5,00 (líquido enviado ao gateway)
- Intervalo entre saques: 5 minutos por conta
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 100.00,
"name": "João Silva",
"cpf": "12345678900",
"keypix": "12345678900",
"tipo_chave": "CPF"
}
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 500.00,
"name": "Empresa LTDA",
"cpf": "12345678000199",
"keypix": "12345678000199",
"tipo_chave": "CNPJ"
}
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 75.50,
"name": "Maria Souza",
"cpf": "98765432100",
"keypix": "maria@email.com",
"tipo_chave": "EMAIL"
}
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 50.00,
"name": "Carlos Oliveira",
"cpf": "11122233344",
"keypix": "11987654321",
"tipo_chave": "PHONE"
}
{
"api-key": "SUA_CHAVE_AQUI",
"amount": 200.00,
"name": "Ana Costa",
"cpf": "55566677788",
"keypix": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tipo_chave": "EVP"
}
$payload = [
'api-key' => 'SUA_CHAVE_AQUI',
'amount' => 100.00,
'name' => 'João Silva',
'cpf' => '12345678900',
'keypix' => 'joao@email.com',
'tipo_chave' => 'EMAIL',
];
$ch = curl_init('https://usesummitpay.com/api/c1/cashout/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 45,
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
// $data['status'] === 'success' → saque processado
const response = await fetch('https://usesummitpay.com/api/c1/cashout/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
'api-key': 'SUA_CHAVE_AQUI',
amount: 100.00,
name: 'João Silva',
cpf: '12345678900',
keypix: 'joao@email.com',
tipo_chave: 'EMAIL',
}),
});
const data = await response.json();
// data.status === 'success' → saque processado
{
"status": "success",
"message": "Saque Realizado",
"id": "52fc5262-4063-4900-933b-55e69850"
}
{
"status": "error",
"message": "Saldo insuficiente"
}
// Cooldown (aguarde 5 min entre saques):
{
"status": "error",
"message": "Aguarde 4 min 12 s para solicitar um novo saque.",
"retry_after_seconds": 252,
"next_allowed_at": "2026-06-17 15:30:00"
}
Respostas de erro comuns
message |
Causa |
|---|---|
Dados incompletos |
Faltam api-key ou amount |
API Key invalida |
Chave inexistente ou incorreta |
Usuario nao encontrado no sistema |
Conta vinculada à chave não encontrada |
Saldo insuficiente |
Saldo disponível menor que amount |
Aguarde X min Y s para solicitar um novo saque. |
Cooldown de 5 minutos entre saques |
Dados de saque inválidos |
CPF, chave ou valor abaixo do mínimo |
| Mensagem do gateway | Recusa da adquirente (chave inválida, titular divergente, etc.) |
IP não autorizado para esta conta... |
Você cadastrou IPs permitidos no painel e o pedido veio de outro IP |
Já existe um saque em processamento para esta conta... |
Outro saque da mesma conta está em andamento; tente de novo em instantes |
Valor inválido / Valor menor que a taxa de saque |
amount zero, negativo ou menor que a taxa |
"status": "pending" |
A adquirente não respondeu a tempo. O valor fica reservado; confira pelo endpoint de status antes de tentar de novo. |
Segurança e repetição
- Idempotency-Key: envie o cabeçalho
Idempotency-Key: <id único do seu pedido>. Se a sua requisição for repetida (por exemplo, por queda de rede), devolvemos a resposta original em vez de fazer outro saque. Vale também para a criação de cobranças. - IPs permitidos: cadastre o IP do seu servidor no painel (Gateway & API). Com pelo menos um IP cadastrado, saques pela API só são aceitos vindos dele, então uma chave vazada não consegue sacar.
Boas práticas
cpf= documento do favorecido.keypix= chave Pix de destino — podem ser diferentes.- Para
CPFeCNPJ, enviekeypixpreferencialmente só com números. - Para
PHONE, aceitamos11999998888ou+5511999998888. - Para
EVP, use o UUID completo retornado pelo banco. - Guarde o
idretornado para conciliação e suporte.
6. Consultar Status (Polling)
Verifique o status de qualquer transação (PIX, Cartão, Boleto ou Cripto) pelo seu ID.
Consulta autenticada (recomendada)
Com a sua chave no cabeçalho X-API-Key, consulte cobranças e saques da sua conta por idTransaction ou external_reference:
curl -H "X-API-Key: SUA_CHAVE" "https://usesummitpay.com/api/v1/transactions/?idTransaction=52fc5262-..."
curl -H "X-API-Key: SUA_CHAVE" "https://usesummitpay.com/api/v1/transactions/?external_reference=pedido-123"
curl -H "X-API-Key: SUA_CHAVE" "https://usesummitpay.com/api/v1/transactions/?type=cashout&idTransaction=..."
# Resposta
{ "type": "charge", "idTransaction": "52fc5262-...", "external_reference": "pedido-123",
"status": "PAID", "status_raw": "PAID_OUT", "amount": 100.5, "net_amount": 97.2,
"method": "PIX", "created_at": "...", "updated_at": "..." }
Consulta pelo ID (legada)
{ "idtransaction": "52fc5262-4063-4900-933b-55e69850" }
$payload = ["idtransaction" => "52fc5262-4063-4900-933b-55e69850"];
$ch = curl_init("https://usesummitpay.com/api/v1/webhook/");
curl_setopt_array($ch, [
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
echo $data['status']; // Ex: PAID_OUT
{ "status": "PAID_OUT" }
Possíveis valores de status
| Status | Significado |
|---|---|
WAITING_FOR_APPROVAL |
Aguardando pagamento |
PAID_OUT |
Pago e confirmado ✅ |
DECLINED |
Cartão recusado pela operadora ❌ |
EXPIRED |
PIX ou boleto expirado |
REFUNDED |
Estornado / devolvido |
7. Simulador de Parcelas
Simule as opções de parcelamento para um valor sem criar uma cobrança. Não requer autenticação.
{
"action": "installments_preview",
"amount": 300.00
}
{
"status": "ok",
"original_amount": 300.00,
"installment_options": [
{ "installments": 1, "installment_value": 300.00, "total_with_fee": 300.00, "monthly_rate": 0, "has_fee": false },
{ "installments": 3, "installment_value": 100.00, "total_with_fee": 300.00, "monthly_rate": 0, "has_fee": false },
{ "installments": 6, "installment_value": 53.06, "total_with_fee": 318.36, "monthly_rate": 1.99, "has_fee": true },
{ "installments": 12, "installment_value": 30.16, "total_with_fee": 361.92, "monthly_rate": 2.99, "has_fee": true }
]
}
8. Webhook — PIX, Cartão e Boleto
Configure a notification_url na criação da cobrança. Quando o pagamento for confirmado,
nossa plataforma enviará um POST para essa URL com o payload abaixo.
{
"status": "PAID_OUT",
"idTransaction": "52fc5262-...",
"amount": 100.50,
"payment_method": "pix",
"paid_at": "2026-01-30 14:30:00"
}
2xx em até 8 segundos. Se não retornar, tentamos de novo em 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h. O histórico de entregas, com botão de reenvio, fica no painel em Gateway & API → Avisos de pagamento.
Trate PAID e PAID_OUT como pago. Dependendo da adquirente, o aviso também pode trazer transactionId, external_reference e method.
Assinatura (confira sempre)
Todo aviso vem assinado com o segredo de assinatura da sua conta (painel → Gateway & API → Avisos de pagamento). Recuse avisos sem assinatura válida: sem essa conferência, qualquer pessoa pode mandar um "pago" falso para a sua URL.
| Cabeçalho | Conteúdo |
|---|---|
X-NovaEra-Signature | sha256= + HMAC-SHA256 hexadecimal de timestamp + "." + corpo_bruto |
X-NovaEra-Timestamp | Unix timestamp do envio. Recuse se tiver mais de 5 minutos. |
X-NovaEra-Delivery | ID único da entrega. O mesmo aviso pode chegar mais de uma vez; use este ID para ignorar repetidos. |
X-NovaEra-Event | Tipo do evento, por exemplo payment.paid |
$body = file_get_contents('php://input'); // corpo bruto, sem decodificar
$ts = $_SERVER['HTTP_X_NOVAERA_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_NOVAERA_SIGNATURE'] ?? '';
$esperado = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, 'SEU_SEGREDO');
if (abs(time() - (int) $ts) > 300 || !hash_equals($esperado, $sig)) {
http_response_code(401);
exit;
}
$evento = json_decode($body, true);
// ... marque o pedido como pago (ignorando X-NovaEra-Delivery já processado)
http_response_code(200);
Modo de teste (Sandbox)
Teste a sua integração sem dinheiro de verdade: crie uma cobrança de teste, simule o pagamento e receba o aviso assinado na sua notification_url, igual ao de produção. Nada disso aparece em vendas nem altera o seu saldo. Use a mesma chave de API.
# 1. Criar cobrança de teste
curl -X POST https://usesummitpay.com/api/v1/sandbox/ -H "X-API-Key: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"action":"charge","amount":10.50,"notification_url":"https://seu-site.com/webhook","external_reference":"pedido-teste-1"}'
# 2. Simular o pagamento (dispara o aviso assinado para a sua notification_url)
curl -X POST https://usesummitpay.com/api/v1/sandbox/ -H "X-API-Key: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"action":"pay","idTransaction":"sbx_..."}'
# 3. Consultar
curl -H "X-API-Key: SUA_CHAVE" "https://usesummitpay.com/api/v1/sandbox/?idTransaction=sbx_..."
"sandbox": true e o cabeçalho X-NovaEra-Event: sandbox.payment.paid. Ignore-os no seu sistema de produção.9. Webhook — Cripto
Os eventos de cripto chegam na URL configurada durante a criação da cobrança, assinados pelo provedor (NOWPayments, Coinbase ou Cryptomus).
{
"idtransaction": "pay_abc123",
"status": "PAID_OUT",
"payment_method": "crypto",
"currency": "USDT",
"network": "trc20",
"amount": 150.00,
"amount_paid": 28.64
}
{
"idtransaction": "pay_abc123",
"status": "EXPIRED",
"payment_method": "crypto",
"currency": "USDT"
}
Códigos de Resposta HTTP
| Código | Significado |
|---|---|
| 200 | Sucesso. Transação criada ou status retornado. |
| 400 | Requisição inválida. Faltam campos obrigatórios ou o JSON está malformado. |
| 401 | API Key inválida ou não encontrada. |
| 422 | Dados inválidos (número de cartão, CPF, e-mail, etc.). Veja o campo detail na resposta.
|
| 502 | Erro ao comunicar com a adquirente. Tente novamente. |
Health Check
Verifique se a API está operacional antes de chamadas críticas.
{ "status": "ok", "timestamp": "2026-01-01T12:00:00Z" }