API de Pagamentos

Bem-vindo à documentação completa da nossa API de pagamentos. Esta API permite que você integre facilmente soluções de pagamento em seu aplicativo ou site, processando transações via PIX.

Início Rápido

Para começar a usar nossa API de pagamentos, você precisará:

Obter suas credenciais de API no painel administrativo
Configurar a autenticação em suas requisições
Implementar o endpoint de webhook para receber atualizações

URL Base da API

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 do API Secret nos cabeçalhos da requisição:

Cabeçalho de Autenticação

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

Nota Você pode obter seu API Secret e seu API Key na seção integrações -> Sunize do painel da sua conta.

Consultar Transação

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

GET https://api.sunize.com.br/v1/transactions/:transaction_id

Parâmetros de URL

Parâmetro	Tipo	Descrição
transaction_id	string	ID único da transação que deseja consultar

Resposta

JSON Response

{
"id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
"external_id": null,
"status": "PENDING",
"amount": 10,
"payment_method": "PIX",
"customer": {
  "name": "Jon doe sudo",
  "email": "[email protected]",
  "phone": "00000000000",
  "document": "24125439095",
  "address": {
    "cep": "32323232",
    "city": "Florianopolis",
    "state": "SC",
    "number": "82",
    "street": "Florianopolis Centro",
    "complement": "ALTOS",
    "neighborhood": "Centro"
  }
},
"created_at": "2025-04-03T20:45:33.855Z"
}

Criar Transação

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

POST https://api.sunize.com.br/v1/transactions

Corpo da Requisição

JSON Request

{
"external_id": "string",
"total_amount": number,
"payment_method": "PIX",
"items": [
  {
    "id": "string",
    "title": "string",
    "description": "string",
    "price": number,
    "quantity": number,
    "is_physical": boolean
  }
],
"ip": "string",
"customer": {
  "name": "string",
  "email": "string",
  "phone": "string", Ex: +5511912345678 (formato internacional E.164)
  "document_type": "CPF" | "CNPJ",
  "document": "string"
}
}

Parâmetros

Abaixo estão os parâmetros necessários para criar uma transação:

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 (atualmente apenas "PIX")
items	array	Lista de itens incluídos na transação
ip	string	Endereço IP do cliente
customer	object	Informações do cliente

Resposta

A API retorna um objeto JSON com os detalhes da transação criada:

JSON Response

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

Status da Transação

Os possíveis valores para o campo status são:

PENDING - Aguardando pagamento
AUTHORIZED - Pagamento aprovado
FAILED - Pagamento falhou
CHARGEBACK - Estorno solicitado
IN_DISPUTE - Em disputa

Erros

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

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

Webhook

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

Payload do Webhook

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

Nota Recomendamos implementar retry e validação de assinatura nos webhooks para garantir a segurança e confiabilidade das notificações.

Boas Práticas

Para garantir a segurança e confiabilidade do seu sistema de webhooks:

Implemente um mecanismo de retry para lidar com falhas temporárias
Verifique a assinatura do webhook para garantir a autenticidade
Responda rapidamente com código 200 para confirmar o recebimento
Processe o webhook de forma assíncrona para evitar timeouts