Skip to main content

​
Fluxo

  1. POST /api/pix/cash-in com transaction e, opcionalmente, payer.
  2. Resposta 201 com id (UUID), geralmente PENDING e, se generateQrCode: true, pixCode (string EMV).
  3. O pagador paga; o parceiro notifica; após processamento, você recebe webhook pix_cash_in (se registrado) e/ou acompanha GET /api/pix/cash-in/{id}.

​
Request (exemplo)

curl -X POST https://api.clearpago.com.br/api/pix/cash-in \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-001" \
  -d '{
    "transaction": {
      "value": 150.75,
      "externalId": "pedido-12345",
      "description": "Pagamento Pedido #12345",
      "expirationTime": 3600,
      "generateQrCode": true
    },
    "payer": {
      "fullName": "João da Silva",
      "document": "123.456.789-00"
    }
  }'

​
Campos principais de transaction

CampoTipoObrigatórioDescrição
valuenumberSimValor em BRL > 0.
externalIdstringSimSeu identificador único.
descriptionstringNãoTexto de cobrança.
expirationTimeintSimSegundos até expirar o QR (ex.: 3600).
generateQrCodeboolNãotrue para receber pixCode (EMV).

​
Response 201 (principais)

CampoDescrição
idUUID do cash-in — persista
statusGeralmente PENDING na criação.
pixCodeString EMV quando generateQrCode: true.
expirationDateValidade do QR.
providerTransactionIdReferência do parceiro.
Dinheiro: o request é em reais; o webhook ao comerciante traz, em geral, value_cents (centavos). Confira a convenção em Convenções.

​
PENDING e PAID

  • PENDING: ainda não liquíduo. Não use como gatilho de liberação de produto, salvo regra de negócio muito explícita (não recomendada).
  • PAID: recebimento confirmado no domínio. Na prática de integração, trate PAID como sucesso financeiro para liberar o pedido; monitore PENDING antigo e estados não terminais (status).

​
QR Code EMV

pixCode segue padrão EMV para Pix (payload copia e cola). A expiração segue expirationTime (segundos) e a data retornada em expirationDate.

​
Quando o pedido “está pago”

  • Critério usual: status PAID (consulta ou cadeia de notificação) + coerência com o ledger se você audita por saldo.
  • PROVIDER_RESULT_UNKNOWN e RECONCILIATION_REQUIRED não são “pedido pago” até convirjam para PAID ou FAILED com política clara. Veja reconciliação.

​
API reference