Chaves PIX Dinâmicas (Repasses e Pagamentos)

Para empresas SaaS, Fintechs, Casas de Apostas e outras que precisam fazer repasses/pagamentos para múltiplas chaves PIX diferentes, a ApexPy permite passar a chave PIX diretamente na requisição, sem necessidade de cadastro prévio.

Quando Usar

Use chaves PIX dinâmicas quando:

• Você precisa fazer pagamentos para diferentes beneficiários
• Os beneficiários mudam frequentemente
• Você não quer cadastrar todas as chaves PIX antecipadamente
• Você está fazendo repasses automáticos (ex: marketplace, plataforma de apostas)

Como Funciona

Ao passar pix_key_type e pix_key_value diretamente na requisição:

1. A ApexPy cria automaticamente um método de saque para aquela chave
2. O método é reutilizado em requisições futuras com a mesma chave
3. Todos os saques são registrados para compliance
4. Não é necessário cadastrar a chave antes de usar

Endpoint

POST /v1/payouts

Parâmetros

* Obrigatório se não passar payout_method_id

Exemplo de Requisição

curl -X POST https://api.apexpy.com.br/v1/payouts \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "pix_key_type": "CPF",
    "pix_key_value": "12345678909",
    "description": "Repasse para vendedor #12345"
  }'

Exemplo com Email

curl -X POST https://api.apexpy.com.br/v1/payouts \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.50,
    "pix_key_type": "EMAIL",
    "pix_key_value": "[email protected]",
    "description": "Pagamento fornecedor - Pedido #789"
  }'

Exemplo com Chave Aleatória

curl -X POST https://api.apexpy.com.br/v1/payouts \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "pix_key_type": "RANDOM",
    "pix_key_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "description": "Prêmio apostador - ID: 456"
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "co_123",
    "status": "pending",
    "amount": 15000,
    "currency": "BRL",
    "payout_method": {
      "id": 45,
      "type": "pix"
    },
    "created_at": "2025-11-29T00:30:00Z",
    "updated_at": "2025-11-29T00:30:00Z"
  }
}

Validações e Segurança

• IP Whitelist obrigatória: Chaves dinâmicas só funcionam via API com IP whitelist configurado
• Dashboard não suporta: No dashboard, você deve cadastrar chaves antes de usar (apenas CPF/CNPJ do seller)
• Reutilização automática: Se você passar a mesma chave novamente, o método já cadastrado será reutilizado
• Logs de compliance: Todas as chaves dinâmicas são registradas com informações completas
• Validação de saldo: O sistema verifica saldo disponível antes de processar

Casos de Uso

1. Marketplace (Repasse para Vendedores)

// Após venda, repassar comissão para vendedor
POST /v1/payouts
{
  "amount": 75.50,
  "pix_key_type": "CPF",
  "pix_key_value": "98765432100",
  "description": "Comissão venda #12345 - Vendedor: João Silva"
}

2. Plataforma de Apostas (Pagamento de Prêmios)

// Pagar prêmio para apostador
POST /v1/payouts
{
  "amount": 1000.00,
  "pix_key_type": "EMAIL",
  "pix_key_value": "[email protected]",
  "description": "Prêmio aposta #789 - Valor: R$ 1.000,00"
}

3. Fintech (Pagamento para Beneficiários)

// Pagar salário/benefício
POST /v1/payouts
{
  "amount": 2500.00,
  "pix_key_type": "CPF",
  "pix_key_value": "11122233344",
  "description": "Salário - Funcionário ID: 456 - Nov/2025"
}

Boas Práticas

• Use descrições claras: Facilita rastreamento e compliance
• Valide chaves antes: Certifique-se de que a chave PIX está correta
• Monitore logs: Acompanhe os saques no dashboard
• Trate erros: Implemente retry para falhas temporárias
• Mantenha histórico: Armazene IDs dos saques no seu sistema

Limitações

• Chaves dinâmicas só funcionam via API (não no dashboard)
• Requer IP whitelist configurada
• Valor mínimo: R$ 1,00
• Valor máximo: Limitado pelo saldo disponível

Diferença: Chave Dinâmica vs Método Cadastrado