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",
  "document_type": "CPF" | "CNPJ",
  "document": "string"
},

"splits": [
  {
    "user_id": "string",
    "type": "percentage" | "fixed",
    "value": number
  }
]

}

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
splits	array	Lista de divisões de pagamento. Cada registro contém: user_id (string) – ID do usuário que receberá parte do valor. type (string) – Tipo do split (`percentage` ou `fixed`). value (number) – Valor do split. • Para `percentage`: informe a porcentagem (ex: 25). • Para `fixed`: informe o valor absoluto em reais (ex: 5.50).

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