ApexPay API

Documentação Técnica

v1.0 Produção
Voltar

Navegação

Documentação da API

ApexPay - Versão 1.0

Autenticação Base URL PIX Cash-In PIX Cash-Out Webhooks Códigos de Erro

Introdução

Bem-vindo à documentação da API do ApexPay. Nossa API permite que você integre pagamentos PIX em sua aplicação de forma simples e segura.

Recursos Disponíveis

  • Criação de cobranças PIX com QR Code
  • Consulta de status de transações
  • Solicitação de saques (Cash-Out)
  • Webhooks para notificações em tempo real
  • Segurança com API Key + API Secret

Autenticação

Todas as requisições à API devem incluir suas credenciais no cabeçalho. Você pode obter suas credenciais no painel do seller.

Métodos de Autenticação Aceitos

O backend aceita HTTP Basic Auth (recomendado) ou X-API-Key + X-API-Secret (compatibilidade).

1) Recomendado: Basic Auth

Authorization: Basic base64(API_KEY:API_SECRET)
Content-Type: application/json

2) Compatibilidade: Headers

X-API-Key: sua_api_key_aqui
X-API-Secret: seu_api_secret_aqui
Content-Type: application/json

Importante

  • • Mantenha suas credenciais em segredo
  • • Nunca exponha suas chaves em repositórios públicos
  • • API Secret é obrigatório em todas as rotas da API (inclusive GET)
  • • No Cash-Out, a whitelist de IP é obrigatória

Ambiente e Base URL

A API está disponível no seguinte endereço: 

Base URL: https://apexpay.top/api

PIX Cash-In (Receber)

Use este endpoint para criar cobranças PIX e receber pagamentos.

Criar Cobrança PIX

POST /api/pix/create

Parâmetros da Requisição

Campo Tipo Obrigatório Descrição
amount decimal Sim Valor da cobrança (ex: 100.00)
customer object Sim Dados do cliente (name, document, email)
external_id string Não ID externo para referência (único)
metadata object Não Dados adicionais personalizados
expires_in_minutes integer Não Tempo de expiração em minutos (padrão atual: 180)
pix_type string Não Tipo do PIX (padrão: dynamic)

Exemplo de Requisição

curl -X POST https://apexpay.top/api/pix/create \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "external_id": "pedido-12345",
    "customer": {
      "name": "João Silva",
      "document": "12345678900",
      "email": "[email protected]"
    }
  }'

Resposta de Sucesso (200 OK)

{
  "success": true,
  "message": "PIX transaction created successfully",
  "data": {
    "transaction_id": "CASHIN_20231204173000_abc123def456",
    "amount": 150.00,
    "fee_amount": 3.75,
    "net_amount": 146.25,
    "status": "pending",
    "qrcode": "00020101021126580014br.gov.bcb.pix...",
    "qrcode_base64": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2023-12-04 20:30:00",
    "external_id": "pedido-12345"
  }
}

Consultar Status da Cobrança

GET /api/pix/consult?transaction_id={transaction_id}

Exemplo de Requisição

curl -X GET "https://apexpay.top/api/pix/consult?transaction_id=CASHIN_20231204173000_abc123def456" \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret"

Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": {
    "transaction_id": "CASHIN_20231204173000_abc123def456",
    "amount": 150.00,
    "fee_amount": 3.75,
    "net_amount": 146.25,
    "status": "paid",
    "qrcode": "00020101021126580014br.gov.bcb.pix...",
    "qrcode_base64": "data:image/png;base64,iVBORw0KGgo...",
    "paid_at": "2023-12-04 17:45:00",
    "expires_at": "2023-12-04 20:30:00",
    "created_at": "2023-12-04 17:30:00",
    "external_id": "pedido-12345"
  }
}

Status Possíveis

pending - Aguardando pagamento
processing - Processando confirmação
paid - Pagamento confirmado
expired - Cobrança expirada
cancelled - Cobrança cancelada
failed - Falha no processamento

Listar Cobranças

GET /api/pix/list

Filtros opcionais: status, start_date, end_date, limit (máximo 100).

curl -X GET "https://apexpay.top/api/pix/list?status=paid&start_date=2026-03-01&end_date=2026-03-06&limit=20" \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret"
{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction_id": "CASHIN_20260306102000_abc123def456",
        "amount": 150.00,
        "fee_amount": 3.75,
        "net_amount": 146.25,
        "status": "paid",
        "paid_at": "2026-03-06 10:22:10",
        "created_at": "2026-03-06 10:20:00"
      }
    ]
  }
}

PIX Cash-Out (Saques)

Use este endpoint para solicitar saques via PIX.

Para Cash-Out, o backend exige IP na whitelist do seller. Requisições fora da whitelist retornam 403.

Solicitar Saque

POST /api/cashout/create

Parâmetros da Requisição

Campo Tipo Obrigatório Descrição
amount decimal Sim Valor do saque (ex: 100.00)
pix_key string Sim Chave PIX de destino
pix_key_type string Sim Tipo: cpf, cnpj, email, phone, random
beneficiary_name string Sim Nome do beneficiário
beneficiary_document string Sim CPF/CNPJ do beneficiário
external_id string Não ID externo para referência (único)
metadata object Não Dados adicionais personalizados

Exemplo de Requisição

curl -X POST https://apexpay.top/api/cashout/create \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "pix_key": "[email protected]",
    "pix_key_type": "email",
    "beneficiary_name": "João Silva",
    "beneficiary_document": "12345678900"
  }'

Resposta de Sucesso (200 OK)

{
  "success": true,
  "message": "Cashout transaction created successfully",
  "data": {
    "transaction_id": "CASHOUT_20231204180000_xyz789ghi012",
    "amount": 500.00,
    "fee_amount": 5.00,
    "total_charged": 505.00,
    "status": "processing",
    "pix_key": "[email protected]",
    "beneficiary_name": "João Silva",
    "external_id": "saque-001"
  }
}

Consultar Status do Saque

GET /api/cashout/consult?transaction_id={transaction_id}

Exemplo de Requisição

curl -X GET "https://apexpay.top/api/cashout/consult?transaction_id=CASHOUT_20231204180000_xyz789ghi012" \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret"

Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": {
    "transaction_id": "CASHOUT_20231204180000_xyz789ghi012",
    "amount": 500.00,
    "fee_amount": 5.00,
    "net_amount": 500.00,
    "status": "completed",
    "pix_key": "[email protected]",
    "beneficiary_name": "João Silva",
    "processed_at": "2023-12-04 18:05:00",
    "created_at": "2023-12-04 18:00:00",
    "external_id": "saque-001"
  }
}

Listar Saques

GET /api/cashout/list

Filtros opcionais: status, start_date, end_date, limit (máximo 100).

curl -X GET "https://apexpay.top/api/cashout/list?status=processing&start_date=2026-03-01&end_date=2026-03-06&limit=20" \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret"
{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction_id": "CASHOUT_20260306101500_xyz789ghi012",
        "amount": 500.00,
        "fee_amount": 5.00,
        "net_amount": 500.00,
        "status": "processing",
        "beneficiary_name": "João Silva",
        "processed_at": null,
        "created_at": "2026-03-06 10:15:00"
      }
    ]
  }
}

Webhooks

Webhooks permitem que você receba notificações automáticas sobre eventos nas suas transações.

Configuração

Configure sua URL de webhook no painel do seller em Configurações → Webhooks.

Requisitos

  • • A URL deve usar HTTPS
  • • O endpoint deve responder com status 200
  • • Resposta deve ser enviada em até 5 segundos
  • • O sistema tentará reenviar até 5 vezes em caso de falha

Eventos de Webhook

Pagamento Recebido (Cash-In)

{
  "type": "pix.cashin",
  "transaction_id": "CASHIN_20231204173000_abc123def456",
  "external_id": "pedido-12345",
  "status": "paid",
  "amount": 150.00,
  "paid_at": "2023-12-04 17:45:00"
}

Cobrança Expirada (Cash-In)

{
  "type": "pix.cashin",
  "transaction_id": "CASHIN_20231204173000_abc123def456",
  "external_id": "pedido-12345",
  "status": "expired",
  "amount": 150.00,
  "paid_at": null
}

Saque Processado (Cash-Out)

{
  "type": "pix.cashout",
  "transaction_id": "CASHOUT_20231204180000_xyz789ghi012",
  "external_id": "saque-001",
  "status": "completed",
  "net_amount": 500.00,
  "fee": 5.00
}

Saque Falhou (Cash-Out)

{
  "type": "pix.cashout",
  "transaction_id": "CASHOUT_20231204180000_xyz789ghi012",
  "external_id": "saque-001",
  "status": "failed",
  "net_amount": 500.00,
  "fee": 5.00,
  "error_message": "Chave Pix nao encontrada"
}

Validando Webhooks

Recomendamos que você valide os webhooks consultando o status da transação via API para confirmar a autenticidade. 

// Exemplo em PHP
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Valide consultando a API
$transactionId = $data['transaction_id'];
$type = $data['type']; // 'pix.cashin' ou 'pix.cashout'

// Faça uma requisição GET para:
// - Cash-in: /api/pix/consult?transaction_id={transaction_id}
// - Cash-out: /api/cashout/consult?transaction_id={transaction_id}

// Compare os dados retornados com os dados do webhook

// Responda com 200 OK
http_response_code(200);
echo json_encode(['success' => true]);

Status de Transações

Os webhooks são enviados para os seguintes status:

paid - Cash-In pago com sucesso
pending - Cash-In aguardando confirmação
completed - Transação concluída com sucesso
processing - Cash-Out em processamento
failed - Transação falhou
cancelled - Transação cancelada
expired - Cobrança expirou (apenas cash-in)

Códigos de Erro

400 Bad Request

Requisição inválida ou parâmetros faltando

{"success":false,"error":{"code":400,"message":"Field 'amount' is required"}}
401 Unauthorized

Credenciais de autenticação inválidas

{"success":false,"error":{"code":401,"message":"Invalid credentials"}}
403 Forbidden

Conta inativa/bloqueada ou IP não autorizado (cash-out)

{"success":false,"error":{"code":403,"message":"Access denied: IP address not authorized"}}
404 Not Found

Transação não encontrada

{"success":false,"error":{"code":404,"message":"Transaction not found"}}
409 Conflict

Conflito de idempotência (ex.: external_id duplicado)

{"success":false,"error":{"code":409,"message":"Duplicate external_id detected. A transaction with this external_id already exists"}}
429 Too Many Requests

Rate limit excedido por endpoint

{"success":false,"error":{"code":429,"message":"Rate limit exceeded. Try again later."}}
500 Internal Server Error

Erro interno do servidor

{"success":false,"error":{"code":500,"message":"Failed to create cashout transaction"}}

Precisa de ajuda? Entre em contato com nosso suporte.

Voltar para a landing