Transferências (cash-out) - OriPay API

Enviar

curl -X POST https://api.oripaysolutions.com.br/v1/pix/transfers \
  -H "Authorization: Bearer $ORIPAY_API_KEY" \
  -H "Idempotency-Key: transfer-saque-991" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "pix_key": "fornecedor@empresa.com.br",
    "external_id": "saque-991",
    "description": "Saque 991",
    "metadata": { "customer_id": "cli_4471" }
  }'

Campo	Obrigatório	Regra
`amount`	Sim	Centavos, de 1 a 100000000 (R$ 1.000.000,00) e dentro do limite
`pix_key`	Sim	CPF, CNPJ, e-mail, celular (`+55...`) ou chave aleatória, até 77 caracteres
`external_id`	Sim	Seu ID, 1 a 64 caracteres `A-Z a-z 0-9 _ -`, único por conta
`description`	Não	Até 140 caracteres
`metadata`	Não	Ver Mapeamento

Campos fora desta lista são recusados com 400 validation_error. Resposta 202:

{
  "id": "0b9d6c1e-3f2a-4b8e-a7d6-5c4b3a291807",
  "external_id": "saque-991",
  "status": "pending",
  "amount": 50000,
  "pix_key_masked": "for***@empresa.com.br",
  "recipient": null,
  "end_to_end_id": null,
  "failure_reason": null,
  "metadata": { "customer_id": "cli_4471" },
  "created_at": "2026-10-28T13:10:00Z",
  "updated_at": "2026-10-28T13:10:00Z"
}

A chave de destino volta só mascarada, em pix_key_masked. Quando o banco informa, recipient traz nome, documento mascarado e nome do banco do recebedor.

O que é debitado

O amount sai do seu saldo no envio. A transferência não tem campo de tarifa: tarifas aparecem como linhas próprias no extrato (pix_fee, monthly_fee). Se a transferência virar failed, o valor volta ao saldo.

Erros comuns

Timeout ou 5xx: repita com a mesma Idempotency-Key. Veja Idempotência.
422 insufficient_balance, velocity_limit_exceeded, pix_key_not_found: não repita sem corrigir.
403 risk_score_exceeded: o antifraude bloqueou. Ver Erros.
transfer.returned: o banco do recebedor devolveu depois. O valor volta ao seu saldo.