Pix Cash-out por QR Code Dinâmico

Visão Geral

Através deste endpoint você pode:

• Realizar pagamentos Pix por QR Code dinâmico
• Pagar utilizando payload EMV do QR Code
• Definir valor máximo para QR Codes com valor variável

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 QR Code Dinâmico

POST /api/v2/baas/pix/payments/payload

Realiza um pagamento Pix utilizando um QR Code dinâmico (payload EMV).

Headers

Campos Obrigatórios

payload (string, obrigatório)

Payload do QR Code Pix (EMV).

• Validações:
  • Obrigatório
  • Deve ser um payload válido de QR Code Pix
  • Formato EMV (padrão brasileiro)
• Exemplo:

  "payload": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***6304ABCD"
  

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 via QR Code"
  

valorMaximo (number, opcional)

Valor máximo permitido para o pagamento (quando o QR Code permite valor variável).

• Validações:
  • Opcional
  • Deve ser um número válido
  • Usado apenas para QR Codes com valor variável
• Exemplo:

  "valorMaximo": 1000.00
  

Exemplo de Requisição

{
  "payload": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***6304ABCD",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Pagamento via QR Code"
}

Resposta de Sucesso (200)

{
  "id": 12346,
  "end_to_end_id": "E12345678202501151234567890123457",
  "value": "150.00",
  "status": "completed",
  "created_at": "2025-01-15 15:00:00",
  "payer": {
    "name": "Seu Nome",
    "document": "11122233344",
    "account": "12345-6"
  },
  "payee": {
    "name": "FULANO DE TAL",
    "document": "12345678901"
  },
  "description": "Pagamento via QR Code"
}

Respostas de Erro

422 - Payload Inválido

{
  "message": {
    "payload": [
      "O payload informado é inválido ou não é um QR Code Pix válido."
    ]
  }
}

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": {
    "payload": [
      "O campo payload é obrigatório."
    ],
    "idempotency_key": [
      "O campo idempotency_key é obrigatório."
    ]
  }
}

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"
}

Regras de Negócio

QR Code Dinâmico

• O QR Code dinâmico contém todas as informações necessárias para o pagamento
• O valor pode estar fixo no QR Code ou ser variável
• Para QR Codes com valor variável, use valorMaximo para limitar o valor máximo

Validação de Payload

• O sistema valida automaticamente se o payload é um QR Code Pix válido
• Payloads inválidos retornam erro de validação
• O formato deve seguir o padrão EMV brasileiro

Idempotência

• Use idempotency_key para evitar pagamentos duplicados
• A mesma chave de idempotência não pode ser usada duas vezes
• Recomenda-se usar UUIDs para garantir unicidade

Próximos Passos

Após realizar pagamentos por QR Code dinâmico, você pode:

1. Realizar pagamento por Chaves Pix
2. Consultar Extrato para verificar a transação
3. Consultar Saldo para verificar saldo atualizado