PayZu Plus API

Bem-vindo à documentação da API PayZu Plus. Nossa API oferece um conjunto robusto de endpoints para integrar funcionalidades de pagamento e assinatura em suas aplicações.

URL Base

http://api.payzuplus.com.br

Autenticação

Todas as requisições à API devem incluir sua chave de API no cabeçalho da requisição.

X-Api-Key: sua_chave_api

Integração PIX

Nossa API PIX permite gerar códigos de pagamento PIX e monitorar seus status. Perfeita para pagamentos imediatos e seguros no Brasil.

Criar Pagamento PIX

POST

Gere um novo código de pagamento PIX com informações opcionais do cliente.

Endpoint

/pix/create

Parâmetros da Requisição

{
  "amount": 100.00,              // Valor do pagamento (obrigatório)
  "webhook": "https://...",      // URL para receber notificações (obrigatório)
  "customer": {                  // Dados do cliente (opcional)
    "nome": "João Silva",
    "email": "[email protected]",
    "document": "123.456.789-00",
    "telefone": "+5511999999999"
  }
}

Exemplos de Código

 100.00,
    'webhook' => 'https://seu-site.com.br/webhook',
    'customer' => [
        'nome' => 'João Silva',
        'email' => '[email protected]',
        'document' => '123.456.789-00',
        'telefone' => '+5511999999999'
    ]
];

$ch = curl_init('http://api.payzuplus.com.brpix/create');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey
    ]
]);

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

print_r($result);

import requests
import json

api_key = 'sua_chave_api'
data = {
    'amount': 100.00,
    'webhook': 'https://seu-site.com.br/webhook',
    'customer': {
        'nome': 'João Silva',
        'email': '[email protected]',
        'document': '123.456.789-00',
        'telefone': '+5511999999999'
    }
}

headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
}

response = requests.post(
    'http://api.payzuplus.com.brpix/create',
    json=data,
    headers=headers
)

result = response.json()
print(result)

Exemplos de Resposta

Resposta de Sucesso (200)

{
  "id": "PIX123456789",
  "qrCodeText": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
  "qrCodeUrl": "https://api.qrserver.com/create-qr-code/?data=00020126580014br.gov.bcb.pix",
  "status": "PENDING"
}

Resposta de Erro (400)

{
  "error": "CPF inválido",
  "details": "DETALHES DO ERRO"
}

Consultar Status do PIX

POST

Consulte o status atual de um pagamento PIX e obtenha detalhes da transação. Use este endpoint para verificar se um pagamento foi recebido e obter informações detalhadas sobre a transação.

Endpoint

/pix/status

Parâmetros da Requisição

{
  "id": "PIX123456789"    // ID da transação PIX (obrigatório)
}

Exemplos de Código

 'PIX123456789'
];

$ch = curl_init('http://api.payzuplus.com.brpix/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey
    ]
]);

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

print_r($result);

import requests
import json

api_key = 'sua_chave_api'
data = {
    'id': 'PIX123456789'
}

headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
}

response = requests.post(
    'http://api.payzuplus.com.brpix/status',
    json=data,
    headers=headers
)

result = response.json()
print(result)

Estados Possíveis

O status da transação pode ser:

pending: PIX gerado, aguardando pagamento
completed: Pagamento recebido com sucesso
expirado: PIX expirou sem receber pagamento
cancelado: Transação foi cancelada

Exemplo de Resposta

{
  "transaction": {
    "id": "PIX123456789",
    "status": "completed",
    "created_at": "2024-02-19 10:00:00",
    "updated_at": "2024-02-19 10:05:00",
    "qr_code": {
      "text": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
      "url": "https://api.qrserver.com/create-qr-code/?data=00020126580014br.gov.bcb.pix"
    }
  },
  "venda": {
    "status": "aprovado",
    "valor": 100.00,
    "created_at": "2024-02-19 10:00:00",
    "comprador": {
      "nome": "João Silva",
      "email": "[email protected]"
    }
  }
}

Gerenciamento de Assinaturas

Crie e gerencie assinaturas recorrentes com cobrança imediata ou com período de teste. Nossa API de assinaturas oferece flexibilidade para diferentes modelos de negócio, permitindo tanto cobranças imediatas quanto períodos de teste gratuitos com conversão automática.

Frequências Disponíveis

semanal: Cobrança a cada 7 dias
mensal: Cobrança a cada 30 dias
bimestral: Cobrança a cada 60 dias
trimestral: Cobrança a cada 90 dias
semestral: Cobrança a cada 180 dias
anual: Cobrança a cada 365 dias

Criar Assinatura com Cobrança Imediata

POST

Crie uma assinatura com cobrança imediata. A primeira cobrança será processada no momento da criação, e as cobranças subsequentes seguirão a frequência do plano escolhido.

Endpoint

/plan/create-signature

Parâmetros da Requisição

{
  "plan_id": "PLAN123",         // ID do plano (obrigatório)
  "customer": {                // Dados do cliente (obrigatório)
    "name": "João Silva",
    "identity": "123.456.789-00",
    "email": "[email protected]",
    "phone": "+5511999999999"
  },
  "payment": {                 // Dados do cartão (obrigatório)
    "card_number": "4111111111111111",
    "security_code": "123",
    "expiration_date": "12/2025",
    "card_holder_name": "JOAO SILVA"
  },
  "send_confirmation": true    // Enviar email de confirmação (opcional)
}

Exemplos de Código

 'PLAN123',
    'customer' => [
        'name' => 'João Silva',
        'identity' => '123.456.789-00',
        'email' => '[email protected]',
        'phone' => '+5511999999999'
    ],
    'payment' => [
        'card_number' => '4111111111111111',
        'security_code' => '123',
        'expiration_date' => '12/2025',
        'card_holder_name' => 'JOAO SILVA'
    ],
    'send_confirmation' => true
];

$ch = curl_init('http://api.payzuplus.com.brplan/create-signature');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey
    ]
]);

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

print_r($result);

import requests
import json

api_key = 'sua_chave_api'
data = {
    'plan_id': 'PLAN123',
    'customer': {
        'name': 'João Silva',
        'identity': '123.456.789-00',
        'email': '[email protected]',
        'phone': '+5511999999999'
    },
    'payment': {
        'card_number': '4111111111111111',
        'security_code': '123',
        'expiration_date': '12/2025',
        'card_holder_name': 'JOAO SILVA'
    },
    'send_confirmation': True
}

headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
}

response = requests.post(
    'http://api.payzuplus.com.brplan/create-signature',
    json=data,
    headers=headers
)

result = response.json()
print(result)

Exemplo de Resposta

{
  "success": true,
  "message": "Transação aprovada",
  "subscription_id": "SUB65d4f789abc123",
  "transaction_id": "TRX987654321",
  "status": "aprovado",
  "valor_liquido": 95.50,
  "data_liberacao": "2024-03-21 10:00:00",
  "proxima_cobranca": "2024-03-21 10:00:00"
}

Criar Assinatura com Período de Teste

POST

Crie uma assinatura com período de teste gratuito. Este endpoint realiza uma pré-autorização de R$1,00 no cartão para validá-lo, mas a primeira cobrança real só ocorrerá após o término do período de teste, que é baseado na frequência do plano selecionado.

Importante

A pré-autorização de R$1,00 é estornada automaticamente em até 7 dias úteis. Este valor não é efetivamente cobrado do cliente.

Endpoint

/plan/create-deferred-signature

Parâmetros da Requisição

{
  "plan_id": "PLAN123",         // ID do plano (obrigatório)
  "customer": {                // Dados do cliente (obrigatório)
    "name": "João Silva",
    "identity": "123.456.789-00",
    "email": "[email protected]",
    "phone": "+5511999999999"
  },
  "payment": {                 // Dados do cartão (obrigatório)
    "card_number": "4111111111111111",
    "security_code": "123",
    "expiration_date": "12/2025",
    "card_holder_name": "JOAO SILVA"
  }
}

Exemplos de Código

 'PLAN123',
    'customer' => [
        'name' => 'João Silva',
        'identity' => '123.456.789-00',
        'email' => '[email protected]',
        'phone' => '+5511999999999'
    ],
    'payment' => [
        'card_number' => '4111111111111111',
        'security_code' => '123',
        'expiration_date' => '12/2025',
        'card_holder_name' => 'JOAO SILVA'
    ]
];

$ch = curl_init('http://api.payzuplus.com.brplan/create-deferred-signature');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey
    ]
]);

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

print_r($result);

import requests
import json

api_key = 'sua_chave_api'
data = {
    'plan_id': 'PLAN123',
    'customer': {
        'name': 'João Silva',
        'identity': '123.456.789-00',
        'email': '[email protected]',
        'phone': '+5511999999999'
    },
    'payment': {
        'card_number': '4111111111111111',
        'security_code': '123',
        'expiration_date': '12/2025',
        'card_holder_name': 'JOAO SILVA'
    }
}

headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
}

response = requests.post(
    'http://api.payzuplus.com.brplan/create-deferred-signature',
    json=data,
    headers=headers
)

result = response.json()
print(result)

Exemplos de Resposta

Resposta de Sucesso (200)

{
  "success": true,
  "message": "Pré-Autorização realizada com sucesso",
  "subscription_id": "SUB65d4f789abc123",
  "transaction_id": "TRX987654321",
  "status": "aprovado",
  "trial_ends_at": "2024-03-21 10:00:00",
  "first_charge_date": "2024-03-21 10:00:00"
}

Resposta de Erro (400)

{
  "error": "Cartão expirado",
  "details": "Verifique os logs"
}

Notas Importantes

O período de teste é baseado na frequência do plano selecionado
A primeira cobrança real ocorrerá automaticamente ao final do período de teste
Um webhook será enviado 3 dias antes do término do período de teste
O cliente pode cancelar a assinatura a qualquer momento durante o período de teste
A pré-autorização de R$1,00 é usada apenas para validar o cartão e é estornada automaticamente

Webhooks

Receba notificações em tempo real sobre o status dos seus pagamentos PIX. Você informará a URL de webhook ao criar um pagamento, e receberá atualizações automáticas quando o status mudar.

Formato do Webhook

O webhook é enviado como uma requisição POST para a URL configurada quando você cria um pagamento PIX. O payload contém informações detalhadas sobre a transação e a venda:

{
"transaction": {
"id": "cm7ceaeqv03jkcgu15mii27nc",
"status": "completed",
"created_at": "2025-02-19 20:58:02",
"updated_at": "2025-02-19 17:58:22",
"amount": 100,
"qr_code": {
"text": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/ea34d2ff-6b0a-46af-9b83-9cbb516204875204000053039865802BR5925PAYZU_INSTITUICAO_DE_PAGA6014TEIXEIRA_DE_FR62070503***6304A70D",
"url": "https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=00020126850014br.gov.bcb.pix2563pix.voluti.com.br%2Fqr%2Fv3%2Fat%2Fea34d2ff-6b0a-46af-9b83-9cbb516204875204000053039865802BR5925PAYZU_INSTITUICAO_DE_PAGA6014TEIXEIRA_DE_FR62070503%2A%2A%2A6304A70D"
}
},
"venda": {
"id": "91",
"status": "aprovado",
"valor": "100.00",
"created_at": "2025-02-19 20:58:02",
"approved_at": "2025-02-19 17:58:22",
"comprador": {
"nome": "Joao silva",
"documento": "11111111111"
}
}
}

Estados Possíveis da Transação

O campo transaction.status pode ter os seguintes valores:

pending: PIX gerado, aguardando pagamento
completed: Pagamento recebido com sucesso
expired: PIX expirou sem receber pagamento
canceled: Transação foi cancelada

Estados Possíveis da Venda

O campo venda.status pode ter os seguintes valores:

pendente: Aguardando pagamento
aprovado: Venda aprovada após recebimento do pagamento
cancelado: Venda cancelada

Implementação de Webhook

Ao receber um webhook, sua aplicação deve:

Verificar a autenticidade do webhook através do cabeçalho X-Payzu-Signature
Processar o webhook de forma assíncrona e responder rapidamente com um código HTTP 200
Implementar lógica de retry em caso de falhas para garantir que todos os eventos sejam processados
Atualizar o status do pedido em seu sistema baseado nos campos transaction.status e venda.status

Dica de Segurança

Para verificar a autenticidade dos webhooks, compare o cabeçalho "X-Payzu-Signature" com o hash HMAC-SHA256 do corpo do webhook usando sua chave secreta.

Códigos de Erro

Lista de códigos de erro que podem ser retornados pela API, com explicações e sugestões para resolução.

Código	Descrição	Solução Sugerida
401	Chave de API inválida	Verifique se está enviando a chave correta no cabeçalho X-Api-Key
4001	Cartão expirado	Solicite um cartão válido ao cliente
4002	Cartão com fundos insuficientes	Solicite outra forma de pagamento
4003	CPF/CNPJ inválido	Verifique o formato e a validade do documento
4004	Plano não encontrado	Verifique o ID do plano informado
5001	Erro de processamento	Entre em contato com suporte técnico
5002	Serviço indisponível	Tente novamente mais tarde

PayZu Plus API

URL Base

Autenticação

Integração PIX

Criar Pagamento PIX

Endpoint

Parâmetros da Requisição

Exemplos de Código

Exemplos de Resposta

Consultar Status do PIX

Endpoint

Parâmetros da Requisição

Exemplos de Código

Estados Possíveis

Exemplo de Resposta

Gerenciamento de Assinaturas

Frequências Disponíveis

Criar Assinatura com Cobrança Imediata

Endpoint

Parâmetros da Requisição

Exemplos de Código

Exemplo de Resposta

Criar Assinatura com Período de Teste

Importante

Endpoint

Parâmetros da Requisição

Exemplos de Código

Exemplos de Resposta

Notas Importantes

Webhooks

Formato do Webhook

Estados Possíveis da Transação

Estados Possíveis da Venda

Implementação de Webhook

Dica de Segurança

Códigos de Erro

Precisa de ajuda?