Documentação da API

Integre o ZaraPay ao seu sistema de forma simples e rápida

Navegação

Base URL: https://zarapay.io/api/v1

Introdução

A API do ZaraPay permite que você integre pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples e segura.

Características

  • API RESTful completa
  • Autenticação via Token Bearer
  • Webhooks em tempo real
  • Respostas em JSON

Obter Credenciais de API

Para usar a API, você precisa gerar uma chave de API no painel do sistema.

Passo 1: Acesse a página de Chaves de API

No painel do sistema, acesse a seção "Chave API" no menu lateral.

Ir para Chaves de API →

Passo 2: Gere uma nova chave

Clique em "Gerar Nova Chave" e dê um nome descritivo (ex: "Site Principal", "App Mobile").

⚠️ Importante: Copie e guarde o token imediatamente, pois ele só será exibido uma vez!

Passo 3: Configure no seu sistema

Adicione o token gerado nas configurações do seu site/aplicação. O token terá o formato:

nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Integração PIX

Crie pagamentos PIX e receba notificações em tempo real quando o pagamento for confirmado.

Endpoint

POST https://zarapay.io/api/v1/payments/pix

Parâmetros

Campo Tipo Obrigatório Descrição
amount float Sim Valor do pagamento (mínimo: R$ 0,01)
payer_name string Sim Nome completo do pagador
payer_email string Sim Email do pagador
payer_cpf string Sim CPF do pagador (apenas números)
description string Não Descrição do pagamento

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "fee": 4.00,
    "amount_net": 96.00,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_key": "00020126580014BR.GOV.BCB.PIX...",
    "expires_at": "2024-11-26T12:30:00Z",
    "expires_in_seconds": 300
  }
}

Cashout - Saques via PIX

Crie saques via PIX para transferir saldo da conta do usuário para uma chave PIX.

Importante: Para saques automáticos funcionarem, você precisa: 1. Configurar o modo de saque como "Automático" ao criar a credencial de API 2. Adicionar o IP do seu servidor nas configurações da API 3. O usuário precisa estar aprovado (KYC) e com saques desbloqueados

Endpoint

POST https://zarapay.io/api/v1/cashout/pix

Parâmetros

Campo Tipo Obrigatório Descrição
amount float Sim Valor líquido desejado (mínimo: R$ 10,00). O sistema calcula automaticamente o valor bruto incluindo taxas.
pix_key string Sim Chave PIX de destino (CPF, Email, Telefone ou Chave Aleatória)

Resposta de Sucesso

{
  "success": true,
  "message": "Saque criado e processado automaticamente.",
  "withdrawal": {
    "id": 123,
    "amount": 95.00,
    "amount_gross": 100.00,
    "fee": 5.00,
    "status": "processing",
    "pix_key": "12345678900"
  }
}

Consultar Transações

Liste e filtre as transações da sua conta ou busque uma transação específica.

Listar Transações

GET https://zarapay.io/api/v1/transactions

Parâmetros (Query String)

Campo Tipo Descrição
status string Filtrar por status (paid, pending, failed, etc)
page integer Número da página
limit integer Itens por página (padrão: 15)

Webhooks (Notificações)

Receba notificações automáticas em seu sistema sempre que o status de uma transação mudar.

Configuração

Configure a URL de callback (Webhook) nas configurações da sua conta ou envie o parâmetro callback_url na criação da transação.

Eventos Disparados

Evento Descrição
payment.created Disparado quando um pagamento é criado.
payment.paid Disparado quando o pagamento é confirmado (pago).
payment.failed Disparado quando o pagamento falha ou expira.

Exemplo de Payload (JSON)

O sistema enviará uma requisição POST para sua URL com o seguinte corpo:

{
  "event": "payment.paid",
  "created_at": "2024-01-20T10:30:00Z",
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference": "PEDIDO_123",
    "status": "paid",
    "amount": 150.00,
    "fee": 4.50,
    "amount_net": 145.50,
    "payer": {
      "name": "João Silva",
      "document": "123.456.789-00",
      "email": "joao@email.com"
    },
    "payment_method": "pix",
    "paid_at": "2024-01-20T10:35:00Z"
  }
}

Resposta Esperada

Seu servidor deve responder com status HTTP 200 OK para confirmar o recebimento. Caso contrário, o sistema tentará reenviar a notificação.

Exemplo em PHP

Exemplo de criação de pagamento PIX usando Guzzle.

<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('https://zarapay.io/api/v1/payments/pix', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'X-Client-ID' => 'SEU_CLIENT_ID',
        'Accept' => 'application/json',
    ],
    'json' => [
        'amount' => 100.00,
        'payer_name' => 'João Silva',
        'payer_email' => 'joao@email.com',
        'payer_cpf' => '12345678900',
        'description' => 'Pagamento de Teste'
    ]
]);

$body = json_decode($response->getBody(), true);
print_r($body);

Exemplo em Python

Exemplo usando a biblioteca requests.

import requests

url = "https://zarapay.io/api/v1/payments/pix"

payload = {
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste"
}

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Exemplo em JavaScript

Exemplo usando fetch API.

const url = "https://zarapay.io/api/v1/payments/pix";

const payload = {
    amount: 100.00,
    payer_name: "João Silva",
    payer_email: "joao@email.com",
    payer_cpf: "12345678900",
    description: "Pagamento de Teste"
};

const headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Exemplo cURL

curl -X POST "https://zarapay.io/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste"
  }'

Códigos de Erro

Lista de possíveis códigos de status HTTP retornados pela API.

Código Significado Descrição
200 OK Requisição processada com sucesso.
201 Created Recurso criado com sucesso (ex: novo pagamento).
400 Bad Request Dados inválidos enviados na requisição. Verifique os campos.
401 Unauthorized Token inválido ou não fornecido.
403 Forbidden Acesso negado ao recurso solicitado.
404 Not Found Recurso não encontrado (ex: transação inexistente).
422 Unprocessable Entity Erro de validação (ex: email inválido, saldo insuficiente).
500 Internal Server Error Erro interno do servidor. Tente novamente mais tarde.