Gateway de Pagamentos

Documentação API ZPay

Integre pagamentos PIX instantâneos na sua aplicação com nossa API simples, segura e de alta disponibilidade.

API v3.0 — Online
Introdução

Como funciona

A API ZPay permite gerar cobranças PIX e realizar transferências de forma programática. Todas as requisições utilizam autenticação por client_id e client_secret.

1

Crie sua conta

Cadastre-se na plataforma ZPay e aguarde a aprovação da sua conta.

2

Obtenha suas credenciais

Acesse o dashboard → API → Credenciais para copiar seu Client ID e Client Secret.

3

Configure o webhook

Informe a URL do seu sistema no parâmetro urlnoty para receber notificações de pagamento.

4

Integre e receba

Use os endpoints abaixo para gerar QR Codes PIX e processar pagamentos automaticamente.

Segurança

Autenticação

Todas as requisições devem incluir client_id e client_secret no corpo da requisição (form-data).

Suas credenciais são únicas e vinculadas à sua conta. Nunca compartilhe o client_secret em código client-side ou repositórios públicos.
URL Base da API
URL 
https://zpaybr.site/v3/pix
POST

Gerar QR Code PIX

Gere QR Codes PIX dinâmicos para receber pagamentos. O QR Code tem validade de 30 minutos.

POST /v3/pix/qrcode.php Gera cobrança PIX
Exemplo PHP
PHP 
// Gerar QR Code PIX
$apiUrl = 'https://zpaybr.site/v3/pix/qrcode.php';

$postData = [
    'client_id'     => 'seu_client_id',
    'client_secret' => 'seu_client_secret',
    'nome'          => 'Nome do Pagador',
    'cpf'           => '12345678900',
    'valor'         => 100.00,
    'descricao'     => 'Pagamento do Pedido #123',
    'urlnoty'       => 'https://seudominio.com/callback',
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $apiUrl,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($postData),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded'],
]);

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

// Exibir QR Code
if ($response['statusCode'] === 200) {
    echo $response['qrcode']; // Código copia e cola
}
Parâmetros
ParâmetroTipoDescrição
client_id obrigatórioStringSeu identificador de cliente
client_secret obrigatórioStringSua chave secreta de autenticação
nome obrigatórioStringNome completo do pagador
cpf obrigatórioStringCPF do pagador (apenas números, 11 dígitos)
valor obrigatórioDecimalValor da cobrança (ex: 100.00). Mínimo: R$ 2,00
descricao opcionalStringDescrição do pagamento (máx. 50 caracteres)
urlnoty opcionalStringURL para receber a notificação quando o PIX for pago
Respostas
Sucesso — 200 OK
JSON 
{
    "statusCode": 200,
    "message": "PIX gerado com sucesso",
    "qrcode": "00020126850014br.gov.bcb.pix...",
    "external_id": "pix_1234567890",
    "transaction_id": "e9ac8caa3a2c700...",
    "gateway": "ZPAY"
}
Erro — 401 Unauthorized
JSON 
{
    "statusCode": 401,
    "message": "Não autenticado"
}
POST

Transferência PIX

Realize transferências PIX para qualquer chave cadastrada. Processamento em tempo real.

POST /v3/pix/payment.php Realiza transferência PIX
O saldo da conta deve ser suficiente para cobrir o valor da transferência mais as taxas aplicáveis.
Exemplo PHP
PHP 
// Transferência PIX
$apiUrl = 'https://zpaybr.site/v3/pix/payment.php';

$postData = [
    'client_id'     => 'seu_client_id',
    'client_secret' => 'seu_client_secret',
    'nome'          => 'Nome do Destinatário',
    'cpf'           => '12345678900',
    'valor'         => 50.00,
    'chave_pix'     => 'destinatario@email.com',
    'urlnoty'       => 'https://seudominio.com/callback',
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $apiUrl,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($postData),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded'],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Parâmetros
ParâmetroTipoDescrição
client_id obrigatórioStringSeu identificador de cliente
client_secret obrigatórioStringSua chave secreta de autenticação
nome obrigatórioStringNome do destinatário
cpf obrigatórioStringCPF do destinatário (apenas números)
valor obrigatórioDecimalValor da transferência (ex: 50.00)
chave_pix obrigatórioStringChave PIX do destinatário (CPF, email, telefone ou EVP)
urlnoty opcionalStringURL para notificação da transferência
Respostas
Sucesso — 200 OK
JSON
{
    "statusCode": 200,
    "message": "Saque PIX processado com sucesso"
}
Erro — 400 Bad Request
JSON
{
    "statusCode": 400,
    "message": "Saldo insuficiente para cobrir valor e taxas."
}
Webhook

Webhook — Pagamento Recebido

Quando um pagamento PIX for confirmado, o sistema envia automaticamente uma requisição POST para o urlnoty informado.

Seu endpoint deve retornar HTTP 200 para confirmar o recebimento. Caso contrário, o sistema tentará reenviar até 3 vezes.
Payload Recebido
JSON 
{
    "requestBody": {
        "transactionType": "RECEIVEPIX",
        "transactionId": "c327ce8bee2a18565ec2m1z...",
        "external_id": "55aefd02e54e785fbb5a80...",
        "amount": 100.00,
        "paymentType": "PIX",
        "status": "PAID",
        "dateApproval": "2024-10-07 16:07:10",
        "creditParty": {
            "name": "Nome do Pagador",
            "taxId": "12345678900"
        }
    }
}
Como processar em PHP
PHP 
$payload = json_decode(file_get_contents('php://input'), true);
$body    = $payload['requestBody'] ?? $payload;

if (($body['status'] ?? '') === 'PAID') {
    $transactionId = $body['transactionId'];
    $externalId    = $body['external_id'];
    $amount        = $body['amount'];

    // Creditar saldo do jogador
    creditarSaldoJogador($externalId, $amount);

    http_response_code(200);
    echo json_encode(['status' => 'ok']);
}
Webhook

Webhook — Transferência Concluída

Notificação enviada quando uma transferência PIX for processada com sucesso.

Payload Recebido
JSON 
{
    "transactionType": "PAYMENT",
    "transactionId": "798176179",
    "external_id": "ebceb2b835598ccad73ce42e...",
    "amount": 50.00,
    "dateApproval": "2024-12-19 17:10:54",
    "statusCode": {
        "statusId": 1,
        "description": "Pagamento aprovado"
    }
}
Referência

Códigos de Erro

A API utiliza códigos HTTP padrão para indicar sucesso ou falha.

Tabela de Erros
CódigoStatusDescrição
200OKRequisição processada com sucesso
400Bad RequestParâmetros inválidos ou ausentes
401UnauthorizedCredenciais inválidas ou não autenticado
403ForbiddenConta sem permissão — contate o suporte
404Not FoundUsuário ou recurso não encontrado
500Server ErrorErro interno — tente novamente
Precisa de ajuda com a integração? Entre em contato com nosso suporte técnico pelo painel da ZPay.