Pix Cash-out por Chaves Pix

Visão Geral

Através deste endpoint você pode:

• Realizar pagamentos Pix por chave
• Agendar pagamentos para datas futuras
• Criar pagamentos recorrentes mensais
• Validar conta antes de realizar pagamento

Autenticação

Esta rota requer:

• Token JWT no header Authorization (autenticação auth:api)
• Assinatura HMAC no header X-Signature (middleware hmac-signature)

Endpoint

Realizar Pagamento por Chave Pix

POST /api/v2/baas/pix/payments/key

Realiza um pagamento Pix utilizando uma chave Pix (CPF, CNPJ, email, telefone ou chave aleatória).

Headers

Campos Obrigatórios

value (integer, obrigatório)

Valor do pagamento em centavos.

• Formato: Número inteiro
• Validações:
  • Obrigatório
  • Deve ser um número inteiro maior que 0
  • Valor mínimo: 1 centavo
• Exemplo:

  {
    "value": 10000
  }
  

  Representa R$ 100,00 (10000 centavos)

key (string, obrigatório)

Chave Pix do beneficiário.

• Validações:
  • Obrigatório quando type_initiation é 1 (chave)
  • Deve ser uma chave Pix válida
  • Tipos aceitos: CPF, CNPJ, email, telefone, chave aleatória (UUID)
• Exemplo:

  {
    "key": "[email protected]"
  }
  

name (string, obrigatório)

Nome do beneficiário.

• Validações:
  • Obrigatório quando type_initiation é 1 (chave)
  • Máximo de 255 caracteres
• Exemplo:

  {
    "name": "João da Silva Santos"
  }
  

ispb (string, obrigatório)

Código ISPB do banco do beneficiário.

• Formato: String numérica
• Validações:
  • Obrigatório
  • Deve ser um código ISPB válido
• Exemplo:

  {
    "ispb": "12345678"
  }
  

agency (string, obrigatório)

Agência bancária do beneficiário.

• Validações:
  • Obrigatório
  • Deve ser uma string válida
• Exemplo:

  {
    "agency": "0001"
  }
  

account (string, obrigatório)

Número da conta bancária do beneficiário.

• Validações:
  • Obrigatório
  • Deve ser diferente da conta do pagador
  • Deve ser uma string válida
• Exemplo:

  {
    "account": "12345-6"
  }
  

account_type (integer, obrigatório)

Tipo de conta do beneficiário.

• Valores possíveis:
  • 1: Conta corrente
  • 2: Conta poupança
• Validações:
  • Obrigatório
  • Deve ser 1 ou 2
• Exemplo:

  {
    "account_type": 1
  }
  

document (string, obrigatório)

Documento do beneficiário (CPF ou CNPJ).

• Validações:
  • Obrigatório
  • Deve ser um CPF ou CNPJ válido
• Exemplo:

  {
    "document": "12345678901"
  }
  

person_type (integer, obrigatório)

Tipo de pessoa do beneficiário.

• Valores possíveis:
  • 1: Pessoa física
  • 2: Pessoa jurídica
• Validações:
  • Obrigatório
  • Deve ser 1 ou 2
• Exemplo:

  {
    "person_type": 1
  }
  

type_initiation (integer, obrigatório)

Tipo de iniciação do pagamento.

• Valores possíveis:
  • 0: Manual (dados bancários)
  • 1: Chave Pix
• Validações:
  • Obrigatório
  • Deve ser 0 ou 1
  • Para pagamento por chave, use 1
• Exemplo:

  {
    "type_initiation": 1
  }
  

idempotency_key (string, obrigatório)

Chave de idempotência para evitar duplicação de pagamentos.

• Validações:
  • Obrigatório
  • Máximo de 36 caracteres
  • Deve ser único por requisição
• Exemplo:

  {
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }
  

Campos Opcionais

description (string, opcional)

Descrição do pagamento.

• Validações:
  • Opcional
  • Máximo de 60 caracteres
• Exemplo:

  {
    "description": "Pagamento de serviços"
  }
  

appointment_date (string, opcional)

Data para agendamento do pagamento.

• Formato: Y-m-d (ano-mês-dia)
• Validações:
  • Opcional
  • Deve ser uma data futura
  • Formato obrigatório: Y-m-d
• Exemplo:

  {
    "appointment_date": "2025-02-01"
  }
  

schedule_months (integer, opcional)

Número de meses para criar pagamento recorrente.

• Validações:
  • Opcional
  • Deve ser um número entre 1 e 12
  • Só pode ser usado junto com appointment_date
• Exemplo:

  {
    "schedule_months": 3
  }
  

Exemplo de Requisição - Pagamento Imediato

{
  "value": 10000,
  "key": "[email protected]",
  "name": "João da Silva Santos",
  "ispb": "12345678",
  "agency": "0001",
  "account": "12345-6",
  "account_type": 1,
  "document": "12345678901",
  "person_type": 1,
  "type_initiation": 1,
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Pagamento de serviços"
}

Exemplo de Requisição - Pagamento Agendado

{
  "value": 50000,
  "key": "[email protected]",
  "name": "Maria Santos",
  "ispb": "12345678",
  "agency": "0001",
  "account": "98765-4",
  "account_type": 1,
  "document": "98765432100",
  "person_type": 1,
  "type_initiation": 1,
  "idempotency_key": "660e8400-e29b-41d4-a716-446655440001",
  "description": "Pagamento mensal",
  "appointment_date": "2025-02-01"
}

Resposta de Sucesso (200)

{
  "id": 12345,
  "end_to_end_id": "E12345678202501151234567890123456",
  "value": "100.00",
  "status": "completed",
  "created_at": "2025-01-15 14:30:00",
  "payer": {
    "name": "Seu Nome",
    "document": "11122233344",
    "account": "12345-6"
  },
  "payee": {
    "name": "João da Silva Santos",
    "document": "12345678901",
    "key": "[email protected]"
  },
  "description": "Pagamento de serviços"
}

Respostas de Erro

400 - Conta em Análise

{
  "message": "Your account is under review. This may take up to 1 business day. Once everything is ready you will be contacted.",
  "error_type": "invalid_user",
  "status": "under_review",
  "document_status": "pending"
}

400 - Transferência para Própria Conta

{
  "message": "You cannot transfer to your own account."
}

422 - Erro de Validação

{
  "message": {
    "value": [
      "O campo value é obrigatório."
    ],
    "key": [
      "O campo key é obrigatório quando type_initiation é 1."
    ],
    "account": [
      "O campo account deve ser diferente da conta do pagador."
    ],
    "appointment_date": [
      "O campo appointment_date deve ser uma data futura."
    ]
  }
}

422 - Saldo Insuficiente

{
  "message": "Insufficient balance to complete the transaction."
}

401 - Não Autenticado

{
  "message": "Unauthorized"
}

403 - Acesso Negado

{
  "message": "Forbidden"
}

429 - Rate Limit Excedido

{
  "message": "Too Many Requests"
}

Próximos Passos

Após realizar pagamentos por chave Pix, você pode:

1. Realizar pagamento por QR Code Dinâmico
2. Consultar Extrato para verificar a transação
3. Consultar Saldo para verificar saldo atualizado