Pagamentos (Payouts)

POST /api/v1/payouts

Envia um pagamento PIX para uma chave de destino usando o saldo disponível da conta do merchant.

Headers

| Header | Obrigatório | Descrição | |---|---|---| | x-api-key | Sim | Sua API Key (sk_live_... ou sk_test_...) | | Content-Type | Sim | application/json |

Requisição

  -H "x-api-key: $CYRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "pixKey": "destinatario@email.com",
    "clientName": "Pedro Costa",
    "clientDoc": "987.654.321-00",
    "description": "Pagamento de serviço"
  }'

Parâmetros do body

| Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | amount | number | Sim | Valor em reais. Mínimo: 0.01 | | pixKey | string | Sim | Chave PIX do destinatário (qualquer tipo) | | clientName | string | Não | Nome do destinatário | | clientDoc | string | Não | CPF ou CNPJ do destinatário | | description | string | Não | Descrição da transferência |

Tipos de chave PIX aceitos

| Tipo | Exemplos | |---|---| | E-mail | usuario@dominio.com | | CPF | 123.456.789-00 ou 12345678900 | | CNPJ | 12.345.678/0001-90 ou 12345678000190 | | Telefone | +5511999999999 | | Chave aleatória | xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx |

Resposta 201 Created

  "transactionId": "cm1xyz789abc012def",
  "endToEndId": "E9876543220240115150000000000001",
  "status": "pending",
  "amount": 150.00,
  "fees": {
    "feeAmount": 0.33,
    "gatewayFeeAmount": 0.13,
    "adminMargin": 0.20,
    "netAmount": 149.67
  }
}

Campos da resposta

| Campo | Tipo | Descrição | |---|---|---| | transactionId | string | ID interno da transação na Cyrus | | endToEndId | string | ID end-to-end PIX do gateway bancário | | status | string | pending — o pagamento está sendo processado | | amount | number | Valor bruto enviado | | fees.feeAmount | number | Taxa total cobrada | | fees.netAmount | number | Valor líquido (amount - feeAmount) |

Fluxo de status

O payout começa como pending. A confirmação chega via webhook:

pending → completed   (webhook: withdrawal.completed)
pending → failed      (nenhum webhook — verificar via /api/v1/transactions)

Taxas

A taxa de R$ 0,33 por payout é debitada do saldo do merchant, não reduz o valor enviado ao destinatário. Portanto o destinatário recebe o valor integral de amount.

Saldo antes: R$ 500,00
Payout de:   R$ 150,00  → destinatário recebe R$ 150,00
Taxa:        R$   0,33
Saldo após:  R$ 349,67

Erros possíveis

| Código HTTP | Mensagem | Causa | |---|---|---| | 400 | Invalid JSON body | Body malformado | | 401 | Unauthorized | API Key ausente ou inválida | | 422 | amount must be a positive number | Valor ausente ou ≤ 0 | | 422 | pixKey is required | Chave PIX ausente | | 502 | Failed to process payout | Falha na comunicação com o gateway |