Pagamento PIX copia e cola

Endpoint para pagar PIX via payload EMV (copia e cola) com débito seguro no saldo do usuário. O sistema sempre aplica a taxa de saque no momento da requisição.

Endpoint: POST /api/payments/pix-copy-paste/pay

Segurança

Valida o payload EMV e o CRC antes de enviar ao gateway.
Aplica taxa de saque por usuário (custom) ou padrão do sistema.
external_id é obrigatório e único (idempotência).
Se o QR já tiver valor embutido (tag 54), esse valor prevalece.

Parâmetro	Tipo	Descrição
payload *	string	PIX copia-e-cola completo (EMV / BR Code).
external_id *	string	ID único da operação no seu sistema.
clientCallbackUrl *	string	Webhook para atualização de status.
amount	number	Use somente quando o QR não possuir valor embutido.
description	string	Descrição da operação.
gateway	string	Opcional. Se não enviar, usa gateway padrão/customizado.

Exemplo de requisição

curl -X POST 'https://api.pulsepag.com/api/payments/pix-copy-paste/pay' \
  --header 'Authorization: Bearer SEU_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "payload": "000201010212...6304ABCD",
    "amount": 15.50,
    "external_id": "qr-pay-20260418-001",
    "description": "Pagamento PIX copia e cola",
    "clientCallbackUrl": "https://seusistema.com/webhooks/pix-qr-pay"
  }'

Exemplo de resposta

{
  "message": "PIX copy-paste payment processed successfully.",
  "transactionId": "87a7f4b8b58e4f9a",
  "withdrawal": {
    "transaction_id": "87a7f4b8b58e4f9a",
    "external_id": "qr-pay-20260418-001",
    "status": "PROCESSING",
    "amount": 15.5,
    "fee": 1.28,
    "total": 16.78,
    "failure_reason": null,
    "type": "Withdrawal"
  }
}

Cálculo financeiro

fee = (amount × withdraw_rate%) + rate_fixed
total = amount + fee
O saldo disponível precisa cobrir o total para aprovar a operação.