> This page is for Internet banking (beta).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Receive

PIX keys and QR codes for **your** account. The payer uses their own bank
app; you find out via webhook and the statement.

Host: `https://client.api.corpx.com`. Writes carry `Idempotency-Key`.

## PIX keys

`GET /v1/accounts/{accountId}/pix/keys` lists keys.

`POST /v1/accounts/{accountId}/pix/keys` registers one. `keyType` accepts
`cpf`, `cnpj`, `random`, `email` and `phone`. Email and phone return
**202** `pending_verification`: the facade sends the OTP and
`POST .../pix/keys/verify` confirms it. A delivery failure is **503**
`otp_send_failed`.

```bash
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"}'
```

For `cpf` / `cnpj`, also send `pixKey` with the holder’s document.
`random` generates an EVP (UUID) — omit `pixKey`.

`DELETE /v1/accounts/{accountId}/pix/keys/{pixKey}` removes a key.

DICT lookup of **another** key (before you pay):
`GET /v1/accounts/{accountId}/pix/key/{pixKey}`. Cached 24h;
`?noCache=true` forces the directory. Lookups consume quota — use them to
show the payee’s name, not to scrape DICT.

## Static QR

Reusable, no expiry. Good for a counter, a site, a donation. The payer
may choose the amount if you omit `value`.

```json
{
  "pixKey": "your-already-registered-key",
  "value": 50.00,
  "message": "Donation"
}
```

`POST /v1/accounts/{accountId}/pix/qr-code/static` → `201` with the EMV
(copy-and-paste) and `identifier`.

## Dynamic QR

One-shot charge, fixed amount, with expiry. Good for an order or invoice.

```json
{
  "pixKey": "your-already-registered-key",
  "value": 150.75,
  "expirationDate": "2026-02-10T15:30:00Z",
  "identifier": "order-12345",
  "message": "Order #12345"
}
```

`pixKey`, `value`, `expirationDate` and `identifier` are required.
`identifier` is the `txid` — unique per account, up to 35 characters. Use
it to match the webhook to the order.

The response has the EMV. Show the QR; **do not** poll. The credit arrives
as `qrcode.paid` and, on the same movement, `pix.in.completed`.

## Look up and cancel

* `GET /v1/accounts/{accountId}/pix/qr-code/lookup?identifier=` — paid,
  waiting or expired
* `DELETE /v1/accounts/{accountId}/pix/qr-code?identifier=` — cancel
* `GET /v1/accounts/{accountId}/pix/qr-codes/stats` — last 24h volume

## When money arrives

Subscribe to [webhooks](/ib/guias/conta/webhooks) with your account’s `accountId`:

| Event              | When                                                                        |
| ------------------ | --------------------------------------------------------------------------- |
| `pix.in.completed` | PIX credit settled (key, QR or refund received)                             |
| `qrcode.paid`      | A QR **you** created was paid — `pix.in.completed` fires on the same credit |

The statement confirms. To track an order, use the QR `identifier` on
lookup or on the statement (`?identifier=`).

## Checklist

* [ ] At least one key (`cpf`, `cnpj` or `random`)
* [ ] Webhook with `pix.in.completed` (and `qrcode.paid` if you issue QRs)
* [ ] HMAC verified on your endpoint
* [ ] Orders reconciled by `identifier`, not by polling the QR