API v1

API de Pagamentos v1

Documentação completa da API v1 de pagamentos — integre transações PIX e cartão de crédito em seu aplicativo ou site. Continua funcionando normalmente e sem previsão de desligamento.

Começar agora Ver API v2

Início rápido

Crie uma credencial v1 no painel, em Integrações → API.
Configure a autenticação em suas requisições.
Implemente o endpoint de webhook para receber atualizações de status.

Precisa de estorno, assinaturas ou UTM? Esses recursos existem na API v2 — crie uma credencial v2 no painel para usá-los.

URL Base

Todas as requisições devem ser feitas para o seguinte domínio base:

BASE https://api.sunize.com.br/v1

Importante Todos os endpoints documentados devem ser anexados a esta URL base. Por exemplo, para criar uma transação, você deve fazer uma requisição para https://api.sunize.com.br/v1/transactions.

Autenticação

A autenticação é feita através das chaves de API nos cabeçalhos da requisição:

Cabeçalhos

x-api-key: SEU_API_KEY
x-api-secret: SEU_API_SECRET

Nota Você pode obter seu API Key e API Secret na seção Integrações → API do painel da sua conta. Ao criar a credencial, escolha a versão v1 — cada credencial funciona só na versão em que foi criada.

x-api-secret é obrigatório Envie sempre o cabeçalho x-api-secret correto — uma requisição sem ele, ou com o valor errado, retorna 401.

Criar Transação

Este endpoint permite criar uma nova transação em nosso sistema.

POST /v1/transactions

Requisição

curl -X POST https://api.sunize.com.br/v1/transactions \
  -H "x-api-key: SEU_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "pedido-1029",
    "total_amount": 149.90,
    "payment_method": "PIX",
    "items": [
      {
        "id": "prod-1",
        "title": "Curso de Marketing",
        "description": "Acesso vitalício",
        "price": 149.90,
        "quantity": 1,
        "is_physical": false
      }
    ],
    "ip": "203.0.113.10",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "phone": "+5511999999999",
      "document_type": "CPF",
      "document": "12345678900"
    }
  }'

const response = await fetch("https://api.sunize.com.br/v1/transactions", {
  method: "POST",
  headers: {
    "x-api-key": process.env.SUNIZE_API_KEY,
    "x-api-secret": process.env.SUNIZE_API_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "pedido-1029",
    total_amount: 149.90,
    payment_method: "PIX",
    items: [
      {
        id: "prod-1",
        title: "Curso de Marketing",
        description: "Acesso vitalício",
        price: 149.90,
        quantity: 1,
        is_physical: false,
      },
    ],
    ip: "203.0.113.10",
    customer: {
      name: "Maria Silva",
      email: "maria@example.com",
      phone: "+5511999999999",
      document_type: "CPF",
      document: "12345678900",
    },
  }),
});

const transaction = await response.json();

<?php

$body = [
    "external_id" => "pedido-1029",
    "total_amount" => 149.90,
    "payment_method" => "PIX",
    "items" => [
        [
            "id" => "prod-1",
            "title" => "Curso de Marketing",
            "description" => "Acesso vitalício",
            "price" => 149.90,
            "quantity" => 1,
            "is_physical" => false,
        ],
    ],
    "ip" => "203.0.113.10",
    "customer" => [
        "name" => "Maria Silva",
        "email" => "maria@example.com",
        "phone" => "+5511999999999",
        "document_type" => "CPF",
        "document" => "12345678900",
    ],
];

$ch = curl_init("https://api.sunize.com.br/v1/transactions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: " . getenv("SUNIZE_API_KEY"),
        "x-api-secret: " . getenv("SUNIZE_API_SECRET"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.post(
    "https://api.sunize.com.br/v1/transactions",
    headers={
        "x-api-key": os.environ["SUNIZE_API_KEY"],
        "x-api-secret": os.environ["SUNIZE_API_SECRET"],
    },
    json={
        "external_id": "pedido-1029",
        "total_amount": 149.90,
        "payment_method": "PIX",
        "items": [
            {
                "id": "prod-1",
                "title": "Curso de Marketing",
                "description": "Acesso vitalício",
                "price": 149.90,
                "quantity": 1,
                "is_physical": False,
            }
        ],
        "ip": "203.0.113.10",
        "customer": {
            "name": "Maria Silva",
            "email": "maria@example.com",
            "phone": "+5511999999999",
            "document_type": "CPF",
            "document": "12345678900",
        },
    },
)

transaction = response.json()

Parâmetros

Parâmetro	Tipo	Descrição
external_id	string	Identificador único externo da transação
total_amount	number	Valor total da transação em reais
payment_method	string	Método de pagamento (`PIX` ou `CREDIT_CARD`)
items	array	Lista de itens incluídos na transação
ip	string	Endereço IP do cliente
customer	object	Informações do cliente. phone no padrão internacional E.164 (ex: +5511999999999). document deve ser um CPF ou CNPJ válido.
splits	array	Opcional. Lista de divisões de pagamento — cada item tem user_id, type (`percentage` ou `fixed`) e value.

Resposta

{
  "id": "string",
  "external_id": "string",
  "status": "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE",
  "total_value": 149.9,
  "customer": { "email": "string", "name": "string" },
  "payment_method": "string",
  "pix": { "payload": "string" },
  "hasError": false
}

Status possíveis

PENDING AUTHORIZED FAILED CHARGEBACK IN_DISPUTE

Consultar Transação

Este endpoint permite consultar os detalhes de uma transação previamente criada.

GET /v1/transactions/:transaction_id

curl https://api.sunize.com.br/v1/transactions/TRANSACTION_ID \
  -H "x-api-key: SEU_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

const response = await fetch(
  `https://api.sunize.com.br/v1/transactions/${transactionId}`,
  {
    headers: {
      "x-api-key": process.env.SUNIZE_API_KEY,
      "x-api-secret": process.env.SUNIZE_API_SECRET,
    },
  }
);

const transaction = await response.json();

<?php

$ch = curl_init("https://api.sunize.com.br/v1/transactions/{$transactionId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: " . getenv("SUNIZE_API_KEY"),
        "x-api-secret: " . getenv("SUNIZE_API_SECRET"),
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.get(
    f"https://api.sunize.com.br/v1/transactions/{transaction_id}",
    headers={
        "x-api-key": os.environ["SUNIZE_API_KEY"],
        "x-api-secret": os.environ["SUNIZE_API_SECRET"],
    },
)

transaction = response.json()

Resposta

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": null,
  "status": "PENDING",
  "amount": 10,
  "payment_method": "PIX",
  "customer": {
    "name": "Jon Doe",
    "email": "jon@example.com",
    "phone": "00000000000",
    "document": "24125439095",
    "address": {
      "cep": "32323232",
      "city": "Florianópolis",
      "state": "SC",
      "number": "82",
      "street": "Florianópolis Centro"
    }
  },
  "created_at": "2025-04-03T20:45:33.855Z"
}

Webhook

Notificações de mudança de status são enviadas para a URL configurada:

Payload

{
  "id": "string",
  "external_id": "string",
  "total_amount": 149.9,
  "status": "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE",
  "payment_method": "string"
}

Nota Recomendamos implementar retry e validação de assinatura nos webhooks. O webhook é enviado com o cabeçalho x-api-secret — use-o para validar a origem da chamada.

Chargeback e estorno chegam com o mesmo status Na v1, tanto um estorno quanto uma disputa de cartão chegam com status: "CHARGEBACK". Se você precisa distinguir os dois casos, considere migrar para a v2, que envia REFUNDED como um status próprio.

Erros

A API pode retornar os seguintes códigos de erro:

Código	Descrição
401	API Key ou API Secret não fornecidos ou inválidos
400	Dados inválidos na requisição
500	Erro interno do servidor

Integrando com ajuda de uma IA?

Publicamos um guia único em Markdown com toda a API v1 — cole no ChatGPT, Claude ou Copilot e peça pra gerar a integração na sua linguagem.