Documentação · API v2
Receba pagamentos da Sunize direto no seu sistema.
Crie cobranças em Pix e cartão, acompanhe cada pagamento por webhook, estorne vendas e cobre assinaturas recorrentes, tudo com uma API REST simples, em JSON.
- URL base
https://api.sunize.com.br/v2- Formato
- JSON em UTF-8
- Autenticação
- 2 cabeçalhos por requisição
- Meios
- Pix, cartão e Pix Automático
Começo
Sua primeira cobrança em 3 passos
Do zero até um Pix gerado leva poucos minutos. Você só precisa de uma conta e de um servidor que faça requisições HTTPS.
- Crie uma credencial
No painel da Sunize, abra Integrações → API → Nova credencial. Você recebe uma
x-api-keye umax-api-secret, e informa a URL que vai receber os webhooks. - Guarde as chaves no servidor
Salve as duas em variáveis de ambiente, como
SUNIZE_API_KEYeSUNIZE_API_SECRET. Elas nunca devem ir para o navegador, para o app nem para o repositório. - Gere um Pix
Chame
POST /v2/transactionscom o pedido. A resposta trazpix.payload, o código copia e cola para mostrar ao comprador. Quando ele pagar, o webhook avisa comAUTHORIZED.
curl -X POST "https://api.sunize.com.br/v2/transactions" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"external_id": "pedido-1042",
"amount": 149.9,
"payment_method": "PIX",
"items": [
{
"id": "curso-online",
"title": "Curso online",
"description": "Acesso vitalício",
"price": 149.9,
"quantity": 1,
"is_physical": false
}
],
"ip": "177.38.12.4",
"customer": {
"name": "Marina Costa",
"email": "marina@email.com",
"phone": "+5511999999999",
"document_type": "CPF",
"document": "12345678909"
},
"tracking": {
"utm_source": "instagram",
"utm_campaign": "lancamento"
}
}'Começo
Autenticação
Toda requisição leva dois cabeçalhos com a sua credencial, inclusive as consultas (GET).
x-api-key: SUA_API_KEY
x-api-secret: SUA_API_SECRET
Content-Type: application/json| Resposta | Quando acontece |
|---|---|
400 | Faltou um dos dois cabeçalhos. |
401 | A chave ou o segredo estão errados, ou a credencial foi apagada. |
401 | A credencial é de outra versão da API. Toda credencial nova já nasce na v2. |
Começo
Valores e regras da API
Poucas regras valem para todos os endpoints. Vale ler antes de escrever a integração.
amount e price são números decimais em reais: 149.90 é R$ 149,90. Nunca envie centavos.
Transações abaixo desse valor são recusadas com 400.
external_id é o id do pedido no seu sistema. Ele volta em todas as respostas e webhooks, então é por ele que você liga a venda ao pedido.
Telefone no formato internacional (+5511999999999), CPF ou CNPJ só com dígitos e o IP real de quem está comprando.
Criar transação
/v2/transactionsCria uma cobrança avulsa por Pix ou cartão de crédito. No Pix, a resposta já traz o código copia e cola; no cartão, a cobrança é processada na hora.
Corpo da requisição
external_idstringobrigatórioId único do pedido no seu sistema. Repita o mesmo valor ao reenviar o mesmo pedido.amountnumberobrigatórioValor total em reais, com até duas casas. Mínimo 5.00.payment_method"PIX" | "CREDIT_CARD"obrigatórioitems[]arrayobrigatórioProdutos do pedido:id,title,description,price,quantityeis_physical(true para produto com entrega).ipstringobrigatórioIP do comprador, IPv4 ou IPv6. Ajuda na análise antifraude.customerobjectobrigatórioname,email,phone(formato +55…),document_type(CPFouCNPJ) edocument(só dígitos).cardobjectno cartãocard_number,card_holder_name,card_expiration_date(MM/AAAA),card_cvveinstallment(número de parcelas). Não envie no Pix.splits[]arrayopcionalDivide a venda com outras contas da Sunize:user_id,type(percentageoufixed) evalue(25 = 25%, ou valor em reais).trackingobjectopcionalUTMs da venda (utm_source,utm_medium,utm_campaign,utm_content,utm_term). Voltam no webhook.
pix.payload como copia e cola (e, se quiser, como QR code). Não considere o pedido pago pela resposta: o pagamento é confirmado pelo webhook.curl -X POST "https://api.sunize.com.br/v2/transactions" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"external_id": "pedido-1043",
"amount": 149.9,
"payment_method": "CREDIT_CARD",
"items": [
{
"id": "curso-online",
"title": "Curso online",
"description": "Acesso vitalício",
"price": 149.9,
"quantity": 1,
"is_physical": false
}
],
"ip": "177.38.12.4",
"customer": {
"name": "Marina Costa",
"email": "marina@email.com",
"phone": "+5511999999999",
"document_type": "CPF",
"document": "12345678909"
},
"tracking": {
"utm_source": "instagram",
"utm_campaign": "lancamento"
},
"card": {
"card_number": "4111111111111111",
"card_holder_name": "MARINA COSTA",
"card_expiration_date": "08/2030",
"card_cvv": "123",
"installment": 3
}
}'{
"id": "tr_8f2c1a",
"external_id": "pedido-1042",
"status": "PENDING",
"amount": 149.9,
"customer": {
"email": "marina@email.com",
"name": "Marina Costa"
},
"payment_method": "PIX",
"pix": {
"payload": "00020126580014br.gov.bcb.pix0136..."
},
"hasError": false
}Transações
Pix sem duplicar
Reenviar o mesmo pedido não gera um Pix novo. Isso protege a sua taxa de conversão.
Se você chamar POST /v2/transactions de novo com o mesmo external_id, o mesmo amount e o mesmo customer.document de um Pix ainda pendente criado nas últimas 6 horas, a API devolve o mesmo Pix (mesmo id, mesmo pix.payload) com "reused": true.
Cada tentativa (erro de rede, página recarregada, fila reenviando) gera um Pix pendente novo. A venda parece ter 3 pendentes e 1 paga, e a conversão despenca.
Todas as tentativas recebem o mesmo Pix. O comprador paga o código que já tem e o relatório mostra a venda real.
Consultar transação
/v2/transactions/:transaction_idBusca o estado atual de uma transação criada pela API. Útil para conferir um pagamento ou recuperar um webhook perdido.
Parâmetro de caminho
transaction_idstringobrigatórioO id devolvido na criação.
curl -X GET "https://api.sunize.com.br/v2/transactions/tr_8f2c1a" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json"{
"id": "tr_8f2c1a",
"external_id": "pedido-1042",
"status": "AUTHORIZED",
"amount": 149.9,
"payment_method": "PIX",
"customer": {
"name": "Marina Costa",
"email": "marina@email.com",
"phone": "+5511999999999",
"document": "12345678909",
"address": null
},
"created_at": "2026-11-05T14:32:10.000Z"
}Estornar transação
/v2/transactions/:transaction_id/refundDevolve o valor ao comprador. É a mesma operação de “Estornar venda” no painel. Não tem corpo.
Para estornar, a venda precisa
- estar
AUTHORIZED; - ter sido criada por esta API;
- ter saldo suficiente em todas as contas que receberam parte dela (produtor, coprodutores e afiliados de split).
Se alguma condição falhar, a resposta é 400 com o motivo.
curl -X POST "https://api.sunize.com.br/v2/transactions/tr_8f2c1a/refund" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json"{
"id": "tr_8f2c1a",
"status": "REFUNDED"
}Assinaturas
Como funcionam as assinaturas
Cobre o mesmo cliente todo ciclo sem pedir o pagamento de novo. Há dois trilhos, no mesmo endpoint.
O comprador autoriza uma única vez (QR code ou link) e as cobranças seguintes caem sozinhas. Vem ativo em toda credencial v2. Ciclos: semanal, mensal ou anual.
A primeira cobrança salva o cartão e as próximas são automáticas. Precisa ser ativado pela nossa equipe. Ciclos: semanal, mensal, bimestral, semestral ou anual.
- 1Você cria a assinatura
- 2Pix: o comprador autoriza · Cartão: já nasce ativa
- 3Cada ciclo cobrado dispara
SUBSCRIPTION_RENEWED - 4Se falhar,
SUBSCRIPTION_LATE; se recuperar,SUBSCRIPTION_RECOVERED
Criar assinatura
/v2/subscriptionsRecebe os mesmos campos da transação avulsa e mais o ciclo de cobrança.
Campos a mais
membership_periodstringobrigatórioSEMANAL,MENSAL,BIMESTRAL,SEMESTRALouANUAL. No Pix Automático, só semanal, mensal ou anual.amountnumberobrigatórioValor cobrado a cada ciclo, não o total.card.installmentnumberno cartãoSempre 1. Assinatura não é parcelada.
items, ip, customer, card, splits e tracking seguem o formato de Criar transação.
PENDING_AUTHORIZATION. Mostre pix.qr_code ou pix.payment_link ao comprador; quando ele autorizar, chega SUBSCRIPTION_AUTHORIZED e ela vira ACTIVE.curl -X POST "https://api.sunize.com.br/v2/subscriptions" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"external_id": "assinatura-77",
"amount": 97,
"payment_method": "PIX",
"membership_period": "MENSAL",
"items": [
{
"id": "clube-mensal",
"title": "Clube mensal",
"description": "Plano mensal",
"price": 97,
"quantity": 1,
"is_physical": false
}
],
"ip": "177.38.12.4",
"customer": {
"name": "Marina Costa",
"email": "marina@email.com",
"phone": "+5511999999999",
"document_type": "CPF",
"document": "12345678909"
}
}'{
"id": "sub_5a90c2",
"external_id": "assinatura-77",
"status": "PENDING_AUTHORIZATION",
"amount": 97,
"membership_period": "MENSAL",
"payment_method": "PIX",
"pix": {
"qr_code": "00020101021226...",
"payment_link": "https://pay.sunize.com.br/pix-automatico/..."
}
}Consultar assinatura
/v2/subscriptions/:subscription_idMostra o estado da assinatura e as datas da última e da próxima cobrança.
Parâmetro de caminho
subscription_idstringobrigatórioO id devolvido na criação.
curl -X GET "https://api.sunize.com.br/v2/subscriptions/sub_5a90c2" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json"{
"id": "sub_5a90c2",
"external_id": "assinatura-77",
"status": "ACTIVE",
"amount": 97,
"membership_period": "MENSAL",
"payment_method": "PIX",
"next_payment_date": "2026-12-05T00:00:00.000Z",
"last_payment_date": "2026-11-05T00:00:00.000Z"
}Cancelar assinatura
/v2/subscriptions/:subscription_id/cancelInterrompe as próximas cobranças. O comprador mantém o acesso até o fim do ciclo já pago. Não tem corpo.
curl -X POST "https://api.sunize.com.br/v2/subscriptions/sub_5a90c2/cancel" \
-H "x-api-key: $SUNIZE_API_KEY" \
-H "x-api-secret: $SUNIZE_API_SECRET" \
-H "Content-Type: application/json"{
"id": "sub_5a90c2",
"status": "CANCELED"
}Webhooks
Como receber webhooks
A cada mudança de status, enviamos um POST para a URL cadastrada na credencial. É assim que você sabe que um Pix foi pago.
- Confira a origem
Todo webhook chega com o cabeçalho
x-api-secret. Compare com o seu segredo e descarte a chamada se for diferente. - Responda 200 rápido
Grave o evento e responda logo. Liberar acesso, mandar e-mail e o resto ficam para depois, fora da requisição.
- Aceite repetição
O mesmo evento pode chegar mais de uma vez. Use
idestatuspara não liberar o mesmo pedido duas vezes.
app.post("/webhooks/sunize", express.json(), async (req, res) => {
if (req.get("x-api-secret") !== process.env.SUNIZE_API_SECRET) {
return res.sendStatus(401);
}
res.sendStatus(200);
const { external_id, status } = req.body;
if (status === "AUTHORIZED") await liberarPedido(external_id);
});Webhooks
Eventos de transação
Enviado quando uma transação muda de status. O corpo traz o estado novo e as UTMs da venda.
{
"id": "tr_8f2c1a",
"external_id": "pedido-1042",
"amount": 149.9,
"status": "AUTHORIZED",
"payment_method": "PIX",
"tracking": {
"utm_source": "instagram",
"utm_medium": null,
"utm_campaign": "lancamento",
"utm_content": null,
"utm_term": null
}
}Webhooks
Eventos de assinatura
O campo event diz o que aconteceu com a assinatura.
| event | Quando chega |
|---|---|
SUBSCRIPTION_CREATED | Assinatura criada (cartão: já ativa; Pix: esperando autorização). |
SUBSCRIPTION_AUTHORIZED | O comprador autorizou o Pix Automático. Ela vira ACTIVE. |
SUBSCRIPTION_RENEWED | A cobrança de um novo ciclo foi aprovada. |
SUBSCRIPTION_LATE | A cobrança do ciclo falhou. |
SUBSCRIPTION_RECOVERED | Uma cobrança que tinha falhado foi paga. |
SUBSCRIPTION_CANCELED | Cancelada pelo comprador, pelo produtor ou pela plataforma. |
{
"event": "SUBSCRIPTION_RENEWED",
"id": "sub_5a90c2",
"external_id": "assinatura-77",
"status": "ACTIVE",
"amount": 97,
"payment_method": "PIX",
"membership_period": "MENSAL",
"next_payment_date": "2026-12-05T00:00:00.000Z"
}Referência
Status
O que cada status significa e o que fazer com ele.
Transação
| Status | Significado |
|---|---|
PENDING | Pix gerado, esperando pagamento. |
AUTHORIZED | Pago. Pode liberar o pedido. |
FAILED | Pagamento recusado ou não concluído. |
REFUNDED | Estornado. Retire o acesso, se for o caso. |
IN_DISPUTE | O comprador contestou e a disputa está em análise. |
CHARGEBACK | Contestação concluída a favor do comprador. É diferente de estorno. |
Assinatura
| Status | Significado |
|---|---|
PENDING_AUTHORIZATION | Pix Automático esperando o comprador autorizar. |
ACTIVE | Em dia. As próximas cobranças acontecem sozinhas. |
LATE | A última cobrança falhou. |
PAUSED | Pausada. Não há cobrança até ser retomada. |
CANCELED | Encerrada. Não há novas cobranças. |
Referência
Erros
Todo erro volta no mesmo formato. errorFields aponta os campos com problema e requestId ajuda o suporte a achar a chamada.
{
"hasError": true,
"error": "Mensagem legível do problema",
"errorFields": [
"customer.phone"
],
"statusCode": 400,
"requestId": "1a5b4e49-476b-4ea1-a117-c6a6cfb7614d",
"timestamp": "2026-11-05T14:32:10.000Z"
}| Código | O que fazer |
|---|---|
400 | Corrija os dados: leia error e errorFields. Também vem quando falta um cabeçalho de autenticação. |
401 | Confira a chave e o segredo, e se a credencial é v2. |
500 | Falha do nosso lado. Tente de novo em instantes e, se continuar, mande o requestId ao suporte. |
Referência
Checklist antes de vender
Confira estes pontos antes de ligar a integração para os seus clientes.
- As chaves estão só no servidor, em variáveis de ambiente.
- Cada pedido tem um
external_idfixo, repetido nas novas tentativas. - O pedido só é liberado pelo webhook com
AUTHORIZED. - O webhook confere o
x-api-secret, responde 200 rápido e aceita repetição. - Estorno, chargeback e disputa retiram o acesso quando for o caso.
- Uma venda real de R$ 5,00 passou pelo fluxo inteiro, do Pix ao webhook.
Referência
Integrar com IA
Qualquer assistente de código escreve esta integração se receber a documentação certa. Preparamos um guia com a API inteira num texto só.
- Pegue o guia
Copie o texto ou baixe o arquivo
.mdpelo botão. - Entregue à IA
No ChatGPT, Claude ou Gemini, cole ou anexe na conversa. No Cursor, Copilot ou Claude Code, salve no projeto (por exemplo
docs/Sunize-API-v2.md) e cite o arquivo no pedido. - Peça a integração
Use o prompt abaixo, trocando a stack e o que você precisa.
- Revise e teste
Compare os campos com esta página e faça uma venda de R$ 5,00 antes de publicar.
Você vai integrar meu sistema com a API de Pagamentos v2 da Sunize.
A documentação completa está no guia em anexo. Siga só o que está nele:
não invente endpoints, campos ou status.
Minha stack: [ex.: Node.js com Express, PHP com Laravel, Python com Django]
O que eu preciso:
- criar cobrança Pix e cartão de crédito;
- receber o webhook e marcar o pedido como pago;
- [opcional] assinaturas recorrentes e estorno.
Regras:
- leia as chaves de SUNIZE_API_KEY e SUNIZE_API_SECRET, nunca no código;
- use o id do pedido como external_id e repita nas novas tentativas;
- no webhook, confira o x-api-secret, responda 200 rápido e trate
eventos repetidos sem liberar o pedido duas vezes;
- trate os erros documentados e me mostre como testar cada parte.