Receber

Chaves PIX e QR codes da sua conta. Quem paga usa o app do banco dele; você fica sabendo pelo webhook e pelo extrato.

Host: https://client.api.corpx.com. Escritas levam Idempotency-Key.

Chaves PIX

GET /v1/accounts/{accountId}/pix/keys lista as chaves.

POST /v1/accounts/{accountId}/pix/keys cadastra. keyType aceita cpf, cnpj, random, email e phone. E-mail e telefone devolvem 202 pending_verification: a facade envia o OTP e POST .../pix/keys/verify confirma. Falha de envio é 503 otp_send_failed.

curl -X POST "https://client.api.corpx.com/v1/accounts/$ACCOUNT_ID/pix/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Idempotency-Key: $UUID" \
  -H "Content-Type: application/json" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $SHA" \
  -H "X-Request-Signature: $SIG" \
  -d '{"keyType":"random"}'

Para cpf / cnpj, envie também pixKey com o documento do titular. random gera um EVP (UUID) — omita pixKey.

DELETE /v1/accounts/{accountId}/pix/keys/{pixKey} remove.

Consulta DICT de outra chave (antes de pagar): GET /v1/accounts/{accountId}/pix/key/{pixKey}. O resultado fica em cache 24h; ?noCache=true força o diretório. Consultas consomem cota — use para mostrar o nome do destinatário, não para varrer o DICT.

QR estático

Reutilizável, sem expiração. Bom para placa, site, doação. O pagador pode escolher o valor se você omitir value.

{
  "pixKey": "sua-chave-ja-cadastrada",
  "value": 50.00,
  "message": "Doação"
}

POST /v1/accounts/{accountId}/pix/qr-code/static → 201 com o EMV (copia-e-cola) e o identifier.

QR dinâmico

Cobrança única, valor fixo, com expiração. Bom para pedido ou fatura.

{
  "pixKey": "sua-chave-ja-cadastrada",
  "value": 150.75,
  "expirationDate": "2026-02-10T15:30:00Z",
  "identifier": "order-12345",
  "message": "Pedido #12345"
}

pixKey, value, expirationDate e identifier são obrigatórios. identifier é o txid — único por conta, até 35 caracteres. Use-o para conciliar o webhook com o pedido.

A resposta traz o EMV. Mostre o QR; não faça polling. O crédito chega em qrcode.paid e, no mesmo movimento, em pix.in.completed.

Consultar e cancelar

• GET /v1/accounts/{accountId}/pix/qr-code/lookup?identifier= — pago, aguardando ou expirado
• DELETE /v1/accounts/{accountId}/pix/qr-code?identifier= — cancela
• GET /v1/accounts/{accountId}/pix/qr-codes/stats — volume das últimas 24h

Quando o dinheiro entra

Assine webhooks com accountId da sua conta:

O extrato confirma. Para rastrear um pedido, use o identifier do QR no lookup ou no extrato (?identifier=).

Checklist

• Pelo menos uma chave (cpf, cnpj ou random)
• Webhook com pix.in.completed (e qrcode.paid se gerar QR)
• HMAC verificado no seu endpoint
• Pedidos conciliados pelo identifier, não por polling do QR