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.

  1. Crie uma credencial

    No painel da Sunize, abra Integrações → API → Nova credencial. Você recebe uma x-api-key e uma x-api-secret, e informa a URL que vai receber os webhooks.

  2. Guarde as chaves no servidor

    Salve as duas em variáveis de ambiente, como SUNIZE_API_KEY e SUNIZE_API_SECRET. Elas nunca devem ir para o navegador, para o app nem para o repositório.

  3. Gere um Pix

    Chame POST /v2/transactions com o pedido. A resposta traz pix.payload, o código copia e cola para mostrar ao comprador. Quando ele pagar, o webhook avisa com AUTHORIZED.

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).

Cabeçalhos
x-api-key: SUA_API_KEY
x-api-secret: SUA_API_SECRET
Content-Type: application/json
RespostaQuando acontece
400Faltou um dos dois cabeçalhos.
401A chave ou o segredo estão errados, ou a credencial foi apagada.
401A credencial é de outra versão da API. Toda credencial nova já nasce na v2.
O segredo é como uma senha
Use as chaves só no seu servidor. Se uma delas vazar, apague a credencial no painel e crie outra: a antiga para de funcionar na hora.

Começo

Valores e regras da API

Poucas regras valem para todos os endpoints. Vale ler antes de escrever a integração.

Valores em reais

amount e price são números decimais em reais: 149.90 é R$ 149,90. Nunca envie centavos.

Mínimo de R$ 5,00

Transações abaixo desse valor são recusadas com 400.

Seu identificador

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.

Dados do comprador

Telefone no formato internacional (+5511999999999), CPF ou CNPJ só com dígitos e o IP real de quem está comprando.

Criar transação

POST/v2/transactions

Cria 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ório
    Id único do pedido no seu sistema. Repita o mesmo valor ao reenviar o mesmo pedido.
  • amountnumberobrigatório
    Valor total em reais, com até duas casas. Mínimo 5.00.
  • payment_method"PIX" | "CREDIT_CARD"obrigatório
  • items[]arrayobrigatório
    Produtos do pedido: id, title, description, price, quantity e is_physical (true para produto com entrega).
  • ipstringobrigatório
    IP do comprador, IPv4 ou IPv6. Ajuda na análise antifraude.
  • customerobjectobrigatório
    name, email, phone (formato +55…), document_type (CPF ou CNPJ) e document (só dígitos).
  • cardobjectno cartão
    card_number, card_holder_name, card_expiration_date (MM/AAAA), card_cvv e installment (número de parcelas). Não envie no Pix.
  • splits[]arrayopcional
    Divide a venda com outras contas da Sunize: user_id, type (percentage ou fixed) e value (25 = 25%, ou valor em reais).
  • trackingobjectopcional
    UTMs da venda (utm_source, utm_medium, utm_campaign, utm_content, utm_term). Voltam no webhook.
Pix: mostre o código e espere o webhook
Exiba 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.

Sem controle

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.

Com o mesmo external_id

Todas as tentativas recebem o mesmo Pix. O comprador paga o código que já tem e o relatório mostra a venda real.

Só vale para Pix
No cartão, cada envio é uma nova tentativa de cobrança, porque é uma ação explícita do comprador.

Consultar transação

GET/v2/transactions/:transaction_id

Busca 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ório
    O id devolvido na criação.
Prefira o webhook
Consultar em laço (polling) atrasa a confirmação e gasta requisições. Use a consulta como conferência, não como meio principal.
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"
Resposta 200
{
  "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

POST/v2/transactions/:transaction_id/refund

Devolve 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"
Resposta 200
{
  "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.

Pix Automático

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.

Cartão recorrente

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.

  1. 1Você cria a assinatura
  2. 2Pix: o comprador autoriza · Cartão: já nasce ativa
  3. 3Cada ciclo cobrado dispara SUBSCRIPTION_RENEWED
  4. 4Se falhar, SUBSCRIPTION_LATE; se recuperar, SUBSCRIPTION_RECOVERED

Criar assinatura

POST/v2/subscriptions

Recebe os mesmos campos da transação avulsa e mais o ciclo de cobrança.

Campos a mais

  • membership_periodstringobrigatório
    SEMANAL, MENSAL, BIMESTRAL, SEMESTRAL ou ANUAL. No Pix Automático, só semanal, mensal ou anual.
  • amountnumberobrigatório
    Valor cobrado a cada ciclo, não o total.
  • card.installmentnumberno cartão
    Sempre 1. Assinatura não é parcelada.

items, ip, customer, card, splits e tracking seguem o formato de Criar transação.

No Pix, mostre a autorização
A assinatura nasce PENDING_AUTHORIZATION. Mostre pix.qr_code ou pix.payment_link ao comprador; quando ele autorizar, chega SUBSCRIPTION_AUTHORIZED e ela vira ACTIVE.
Quando volta 400
Cartão recorrente não ativado na conta, cartão recusado (a assinatura não é criada) ou ciclo bimestral/semestral pedido no Pix Automático.
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

GET/v2/subscriptions/:subscription_id

Mostra o estado da assinatura e as datas da última e da próxima cobrança.

Parâmetro de caminho

  • subscription_idstringobrigatório
    O 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"
Resposta 200
{
  "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

POST/v2/subscriptions/:subscription_id/cancel

Interrompe 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"
Resposta 200
{
  "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.

  1. 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.

  2. 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.

  3. Aceite repetição

    O mesmo evento pode chegar mais de uma vez. Use id e status para não liberar o mesmo pedido duas vezes.

Exemplo em Node.js (Express)
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.

Corpo do webhook
{
  "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.

eventQuando chega
SUBSCRIPTION_CREATEDAssinatura criada (cartão: já ativa; Pix: esperando autorização).
SUBSCRIPTION_AUTHORIZEDO comprador autorizou o Pix Automático. Ela vira ACTIVE.
SUBSCRIPTION_RENEWEDA cobrança de um novo ciclo foi aprovada.
SUBSCRIPTION_LATEA cobrança do ciclo falhou.
SUBSCRIPTION_RECOVEREDUma cobrança que tinha falhado foi paga.
SUBSCRIPTION_CANCELEDCancelada pelo comprador, pelo produtor ou pela plataforma.
Corpo do webhook
{
  "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

StatusSignificado
PENDINGPix gerado, esperando pagamento.
AUTHORIZEDPago. Pode liberar o pedido.
FAILEDPagamento recusado ou não concluído.
REFUNDEDEstornado. Retire o acesso, se for o caso.
IN_DISPUTEO comprador contestou e a disputa está em análise.
CHARGEBACKContestação concluída a favor do comprador. É diferente de estorno.

Assinatura

StatusSignificado
PENDING_AUTHORIZATIONPix Automático esperando o comprador autorizar.
ACTIVEEm dia. As próximas cobranças acontecem sozinhas.
LATEA última cobrança falhou.
PAUSEDPausada. Não há cobrança até ser retomada.
CANCELEDEncerrada. 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.

Resposta de erro
{
  "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ódigoO que fazer
400Corrija os dados: leia error e errorFields. Também vem quando falta um cabeçalho de autenticação.
401Confira a chave e o segredo, e se a credencial é v2.
500Falha 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_id fixo, 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ó.

  1. Pegue o guia

    Copie o texto ou baixe o arquivo .md pelo botão.

  2. 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.

  3. Peça a integração

    Use o prompt abaixo, trocando a stack e o que você precisa.

  4. Revise e teste

    Compare os campos com esta página e faça uma venda de R$ 5,00 antes de publicar.

Prompt pronto
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.
Nunca cole as chaves na IA
Mande só os nomes das variáveis de ambiente. Se uma chave vazar, apague a credencial no painel e crie outra.

Integrar com IA

O guia reúne a API inteira num texto só, escrito para ser lido por IA. Funciona no ChatGPT, Claude, Gemini, Copilot, Cursor ou qualquer outra.

Ver o passo a passo e o prompt pronto