HELP CENTER

Help Center

Everything that applies to every route: how to authenticate, idempotency, errors, and how to move from another provider.

Authentication and permissions

Use the 1-hour token from /oauth/token as Authorization: Bearer. Ask for a new one shortly before expiry or on a 401. The raw sk_ key as Bearer also works. The key defines what the token can do: the scope field of the request is ignored.

Scope	Your key permission	Routes
`account.read`	`balance:read`	GET /accounts/balances
`transactions.read`	`transactions:read`	GET /accounts/transactions
`pix.read / cob.read`	`pix:read`	GET /accounts/keys, GET /pix/payments/*, GET /cob/{txid}
`pix.write`	`pix:send`	POST /pix/payments/dict
`cob.write`	`pix:write`	PUT /cob/{txid}, POST /cob
`internal-transfer.write`	`transfers:write`	POST /internal-transfers
`internal-transfer.read`	`transactions:read`	GET /internal-transfers/{endToEndId}, GET /internal-transfers/idempotencyKey/{key}

Client certificate (mTLS): optional by default. If your bank turned the requirement on for your account, calls must present it (403 certificate_required otherwise).

Other functions on your account

Besides the routes on this page, your bank enabled these functions in the v1 API. The same token (Authorization: Bearer) works on them; the full reference for each is in the v1 documentation.

Function	Routes	Key permission
`Transfer between accounts (also in v2: /internal-transfers)`	POST /v1/transfers	transfers:write
`Payment links`	POST /v1/payment-links, GET /v1/payment-links	pix:write
`Split of incoming payments`	GET/PUT /v1/split, GET /v1/split/lookup, GET /v1/split/history	split:read, split:write
`Split to a Pix key`	PUT /v1/split/pix	split:write
`Payroll`	/v1/payroll/*	payroll:read, payroll:write

Full reference: /docs (v1 API).

Idempotency

Every payment requires the x-idempotency-key header (1 to 50 letters and digits). Repeating the same key returns the SAME payment, never paying twice. If the connection drops and you do not know whether the request arrived, repeat it with the same key or call GET /pix/payments/idempotencyKey/{key}.

Errors

{
  "type": "onz-0008",
  "title": "Invalid request",
  "status": 400,
  "detail": "Saldo insuficiente",
  "instance": "/api/v2/pix/payments/dict",
  "statusCode": 400,
  "error": "insufficient_funds",
  "message": "Saldo insuficiente"
}

type	title	When
`onz-0001`	Invalid credentials	Invalid clientId or clientSecret (401)
`onz-0002`	Invalid params	Missing or invalid field; the message says which (400)
`onz-0003`	Invalid token	Missing, invalid or expired token, or revoked key (401)
`onz-0004`	Internal server error	Our failure; keep the ref (500)
`onz-0005`	Server shutting down	System busy: retry shortly (503)
`onz-0006`	Invalid token role	The key lacks the route's permission, the bank turned the function off or the mTLS certificate is missing (403)
`onz-0007`	Invalid pix entry	Invalid Pix key (400)
`onz-0008`	Invalid request	A business rule refused it (balance, limit, recipient…), call limit or a route the bank does not have. Nothing was debited (400, 429, 501)
`onz-0009`	Pix not found	Payment, charge or transfer not found in this account (404)
`onz-0010`	Invalid QR code	Invalid QR code, or an amount different from the one sent (400)
`onz-0011`	Invalid idempotency key	The x-idempotency-key is missing or invalid (400)
`onz-0012`	Webhook not found	Webhook not found (404)

The error body carries type (the onz-XXXX code from the table), title, status, detail and instance, as well as statusCode, error (the detailed code, such as insufficient_funds) and message. Decide by the HTTP status and the type; the error field gives the exact reason. On a 5xx error a ref also comes back: keep it when contacting support.

Migrating from another provider

Change the base URL to https://bank.granseuk.com/api/v2.
Replace clientId and clientSecret with those of your key (see Authentication).
POST /pix/payments/dict answers 202 with { endToEndId, eventDate, id, payment, type }. endToEndId may be null until the Pix moves on; look it up by idempotency key.
GET /pix/payments/{endToEndId} returns { data: {...} }. It also accepts the transactionId.
The id field is a stable number, but it cannot be used for lookups: use endToEndId or transactionId.
The error codes (type onz-XXXX) and the scope names the token returns (pix.write, cob.write, account.read…) are the same; when creating the key in the panel, permissions have their own names (pix:send, pix:write…): see the permissions table.

Not available yet

Creating Pix keys by API (keys are created in the panel) and refunding a received Pix.
Bank slips (/billets) and TED in this format.
Charges with due date (/cobv), recurring (/cobr) and Pix Automático.
Sandbox keys (sk_sbx_) cannot exchange a token; use v1 to test without real money.

Routes of this standard that do not exist yet answer 501 not_supported, with an explanation (for example, POST /accounts/keys).

Integrating with AI

This whole documentation, as plain text, is at /docs/v2/llms.txt (add ?lang=en for English). Paste it into your assistant and ask for the code.