{ "openapi": "3.0.3", "info": { "title": "Accounts API", "version": "2.0.0", "description": "Accounts API Overview\n\nCheck the balance and statement, send Pix by key, follow each payment through to confirmation, get the receipt, transfer between accounts of the bank." }, "servers": [ { "url": "https://bank.granseuk.com/api/v2" } ], "tags": [ { "name": "Authentication" }, { "name": "Account" }, { "name": "Pix" }, { "name": "Transfer between accounts" } ], "paths": { "/oauth/token": { "post": { "tags": [ "Authentication" ], "summary": "Get an access token", "description": "Exchanges clientId and clientSecret for an access token (OAuth 2.0 client credentials). The token is valid for 1 hour; send it as Authorization: Bearer on every other route. Accepts JSON, a form body (client_id, client_secret, grant_type) or Authorization: Basic base64(clientId:clientSecret).\n\nexpiresAt is the expiry instant in Unix seconds.\n\nThe token stops working the moment its key is revoked.", "operationId": "oauthToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "description": "The first 14 characters of your API key (e.g. sk_live_AbCdEf) or the key id." }, "clientSecret": { "type": "string", "description": "The full API key (sk_live_…)." }, "grantType": { "type": "string", "description": "Always client_credentials." }, "scope": { "type": "string", "description": "Ignored: the token carries all of the key's permissions." } }, "required": [ "clientId", "clientSecret", "grantType" ] }, "example": { "clientId": "sk_live_AbCdEf", "clientSecret": "sk_live_AbCdEf…chave-completa", "grantType": "client_credentials" } } } }, "responses": { "201": { "description": "Token issued", "content": { "application/json": { "example": { "tokenType": "Bearer", "expiresAt": 1792529169, "refreshExpiresIn": 0, "notBeforePolicy": 0, "accessToken": "v2t_Zk3q…", "scope": "account.read transactions.read pix.read cob.read cob.write pix.write" } } } }, "401": { "description": "Invalid clientId/clientSecret, or revoked/expired key", "content": { "application/json": { "example": { "type": "onz-0001", "title": "Invalid credentials", "status": 401, "detail": "clientId ou clientSecret invalidos, ou chave revogada/expirada", "instance": "/api/v2/oauth/token", "statusCode": 401, "error": "invalid_client", "message": "clientId ou clientSecret invalidos, ou chave revogada/expirada" } } } } }, "security": [] } }, "/accounts/balances": { "get": { "tags": [ "Account" ], "summary": "Get the account balance", "description": "Balance in BRL. available is what can be spent now; blocked is what is on hold (by a bank review, for example).", "operationId": "balances", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": [ { "eventDate": "2026-10-20T14:00:00.000Z", "balanceAmount": { "currency": "BRL", "available": 1234.56, "blocked": 0, "overdraft": 0 } } ] } } } } }, "security": [ { "OAuth2": [ "account.read" ] } ] } }, "/accounts/transactions": { "get": { "tags": [ "Account" ], "summary": "List account transactions", "description": "The account statement, newest first. Dates are inclusive (Sao Paulo time zone).\n\ncreditDebitType: CREDIT is money in, DEBIT is money out. transactionAmount.available and amount carry the same value.", "operationId": "transactions", "parameters": [ { "name": "event_date_start", "in": "query", "required": false, "description": "Start date (ISO 8601; only the day is used).", "schema": { "type": "string", "format": "date-time" } }, { "name": "event_date_end", "in": "query", "required": false, "description": "End date (ISO 8601; only the day is used).", "schema": { "type": "string", "format": "date-time" } }, { "name": "page_offset", "in": "query", "required": false, "description": "Start position (items to skip). Default 0.", "schema": { "type": "integer" } }, { "name": "page_limit", "in": "query", "required": false, "description": "Items per page, up to 100. Default 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "meta": { "total": 1, "limit": 25, "offset": 0 }, "data": [ { "eventDate": "2026-10-20T14:03:14.000Z", "id": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "status": "LIQUIDATED", "endToEndId": "E3187249520261020184600abcdEFGH12345", "txId": null, "creditDebitType": "DEBIT", "transactionType": "PIX", "transactionAmount": { "currency": "BRL", "available": 25.5, "amount": 25.5 }, "fee": 0.5, "description": "Repasse pedido 1042", "counterparty": { "name": "Fulano de Tal" } } ] } } } } }, "security": [ { "OAuth2": [ "transactions.read" ] } ] } }, "/accounts/keys": { "get": { "tags": [ "Account" ], "summary": "List the account Pix keys", "description": "The Pix keys the bank generated for your account. Whoever pays a key chooses the amount in their bank app. Keys are created in the bank panel; this API is read-only.", "operationId": "keys", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": [ { "key": "9d2c41a7-6f0e-4b53-8a21-3c5e7b9f0d14", "keyType": "EVP", "branch": null, "accountNumber": null, "accountType": null, "name": "Sua Empresa LTDA", "tradeName": null, "taxIdNumber": null, "creationDate": "2026-10-20T18:45:32.244Z", "keyOwnershipDate": "2026-10-20T18:45:32.244Z", "status": "ACTIVE" } ] } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/dict": { "post": { "tags": [ "Pix" ], "summary": "Start a Pix payment by Pix key", "description": "Sends a Pix to a key (CPF, CNPJ, e-mail, phone or EVP, the random key). The amount is debited right away and the payment is accepted for processing (202). The outcome (LIQUIDATED or CANCELED) comes from the lookup by endToEndId or by idempotency key. If it is refused, the amount returns to the account.\n\nendToEndId may be null in the 202: it appears as soon as the Pix goes on to the destination bank. Look it up by idempotency key or by transactionId.\n\nid is a stable number; to look it up use endToEndId or transactionId.", "operationId": "pixDict", "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "description": "Unique request identifier (1 to 50 letters and digits). Repeating the same key returns the SAME payment, never paying twice.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "The destination Pix key." }, "pixKeyType": { "type": "string", "description": "CPF | CNPJ | EMAIL | PHONE | EVP" }, "payment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in BRL, up to 2 decimals." }, "currency": { "type": "string", "description": "BRL." } } }, "description": { "type": "string", "description": "Pix text, up to 140 characters." } }, "required": [ "pixKey", "pixKeyType" ] }, "example": { "pixKey": "fulano@exemplo.com", "pixKeyType": "EMAIL", "payment": { "currency": "BRL", "amount": 25.5 }, "description": "Repasse pedido 1042" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "endToEndId": null, "eventDate": "2026-10-20T14:03:11.000Z", "id": 218394857201, "payment": { "currency": "BRL", "amount": 25.5 }, "type": "PIX", "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "status": "PROCESSING", "fee": 0.5 } } } }, "400": { "description": "Business rule or invalid field (balance, limit, invalid key…). Nothing was debited.", "content": { "application/json": { "example": { "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" } } } } }, "security": [ { "OAuth2": [ "pix.write" ] } ] } }, "/pix/payments/{endToEndId}": { "get": { "tags": [ "Pix" ], "summary": "Get a Pix by end-to-end id", "description": "The full payment. Accepts the Pix endToEndId or the transactionId returned on creation. 404 if it is not a payment of your account.\n\nstatus: PROCESSING, LIQUIDATED, CANCELED, REFUNDED or WAITING_APPROVAL.", "operationId": "pixE2e", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "The Pix endToEndId (or the transactionId).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "id": 218394857201, "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "endToEndId": "E3187249520261020184600abcdEFGH12345", "pixKey": "fulano@exemplo.com", "transactionType": "PIX", "status": "LIQUIDATED", "errorCode": null, "localInstrument": null, "creditDebitType": "DEBIT", "createdAt": "2026-10-20T14:03:11.000Z", "settledAt": "2026-10-20T14:03:14.000Z", "creditorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": "Fulano de Tal" }, "debtorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": null }, "remittanceInformation": "Repasse pedido 1042", "txId": null, "payment": { "currency": "BRL", "amount": 25.5 }, "fee": 0.5, "refunds": [] } } } } }, "404": { "description": "Payment not found in this account", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Pagamento nao encontrado", "instance": "/api/v2/pix/payments/{endToEndId}", "statusCode": 404, "error": "not_found", "message": "Pagamento nao encontrado" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/idempotencyKey/{idempotencyKey}": { "get": { "tags": [ "Pix" ], "summary": "Get a Pix by idempotency key", "description": "The same payment, found by the x-idempotency-key you sent. Use it after a timeout to find out whether the request arrived.", "operationId": "pixIdem", "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "description": "The request idempotency key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "id": 218394857201, "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "endToEndId": "E3187249520261020184600abcdEFGH12345", "pixKey": "fulano@exemplo.com", "transactionType": "PIX", "status": "PROCESSING", "errorCode": null, "localInstrument": null, "creditDebitType": "DEBIT", "createdAt": "2026-10-20T14:03:11.000Z", "settledAt": null, "creditorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": "Fulano de Tal" }, "debtorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": null }, "remittanceInformation": "Repasse pedido 1042", "txId": null, "payment": { "currency": "BRL", "amount": 25.5 }, "fee": 0.5, "refunds": [] } } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/receipt/{endToEndId}": { "get": { "tags": [ "Pix" ], "summary": "Get the Pix receipt as a PDF", "description": "The payment receipt as a base64-encoded PDF (with the bank's branding). Accepts the endToEndId or the transactionId.", "operationId": "pixReceipt", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "The Pix endToEndId (or the transactionId).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "pdf": "JVBERi0xLjQK…" } } } } }, "404": { "description": "Payment not found in this account", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Pagamento nao encontrado", "instance": "/api/v2/pix/payments/receipt/{endToEndId}", "statusCode": 404, "error": "not_found", "message": "Pagamento nao encontrado" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/keys/{key}": { "get": { "tags": [ "Pix" ], "summary": "Look up a Pix key", "description": "What the DICT says about any Pix key: name, document (masked by the DICT itself) and bank. Use it to confirm the recipient before sending. If the bank's provider does not query the DICT, it answers 501 not_supported.", "operationId": "pixKeyDict", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "The Pix key (CPF, CNPJ, e-mail, phone or random).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "name": "Fulano de Tal", "tradeName": null, "keyType": "EMAIL", "key": "fulano@exemplo.com", "document": "***.456.789-**", "ispb": "00000000", "ispb_reduced_name": "Banco Exemplo", "endToEndId": null } } } }, "404": { "description": "Key not found", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Chave Pix nao encontrada", "instance": "/api/v2/pix/keys/{key}", "statusCode": 404, "error": "not_found", "message": "Chave Pix nao encontrada" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/internal-transfers": { "post": { "tags": [ "Transfer between accounts" ], "summary": "Create a transfer between accounts", "description": "Transfers to another account at this same bank, instantly and without going through Pix. The destination account is found by the holder's document (CPF or CNPJ), and the name you send must match the account: if any check fails, nothing is transferred. Repeating the same x-idempotency-key returns the same transfer.\n\nIt does not go through Pix: the transfer is created already settled (LIQUIDATED) and endToEndId is null.", "operationId": "itCreate", "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "description": "Unique request identifier (1 to 50 letters and digits).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditorAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ of the destination account holder." }, "name": { "type": "string", "description": "Holder name. Must match the account." }, "number": { "type": "string", "description": "Optional: the destination account id, as an extra check." } } }, "payment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in BRL, up to 2 decimals." } } }, "remittanceInformation": { "type": "string", "description": "Description, up to 200 characters." } } }, "example": { "creditorAccount": { "document": "12345678909", "name": "Fulano de Tal", "number": "", "accountType": "TRAN" }, "payment": { "currency": "BRL", "amount": 100 }, "remittanceInformation": "Acerto do pedido 1042" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "endToEndId": null, "status": "LIQUIDATED", "transactionType": "INTERNAL", "createdAt": "2026-10-20T14:20:00.000Z", "eventDate": "2026-10-20T14:20:00.000Z", "idempotencyKey": "acerto1042", "payment": { "currency": "BRL", "amount": 100 }, "creditorAccount": { "document": null, "name": "Fulano de Tal", "issuer": null, "number": "8b1e…", "accountType": "TRAN", "ispb": null }, "debtorAccount": { "document": null, "name": "Sua Empresa LTDA", "issuer": null, "number": "c24f…", "accountType": "TRAN", "ispb": null }, "remittanceInformation": "Acerto do pedido 1042", "refunds": [], "fee": 0 } } } } }, "400": { "description": "Name differs from the holder (recipient_name_mismatch), balance, limit… Nothing was transferred.", "content": { "application/json": { "example": { "type": "onz-0008", "title": "Invalid request", "status": 400, "detail": "O nome informado não confere com o titular da conta de destino. Nada foi transferido.", "instance": "/api/v2/internal-transfers", "statusCode": 400, "error": "recipient_name_mismatch", "message": "O nome informado não confere com o titular da conta de destino. Nada foi transferido." } } } }, "404": { "description": "No account at this bank with that document (recipient_not_found)", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Não há conta neste banco com esse documento", "instance": "/api/v2/internal-transfers", "statusCode": 404, "error": "recipient_not_found", "message": "Não há conta neste banco com esse documento" } } } } }, "security": [ { "OAuth2": [ "internal-transfer.write" ] } ] } }, "/internal-transfers/{endToEndId}": { "get": { "tags": [ "Transfer between accounts" ], "summary": "Get a transfer between accounts", "description": "The transfer by endToEndId (when there is one) or by the transactionId returned on creation.", "operationId": "itGet", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "The endToEndId or the transactionId.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "status": "LIQUIDATED", "transactionType": "INTERNAL", "payment": { "currency": "BRL", "amount": 100 } } } } } } }, "security": [ { "OAuth2": [ "internal-transfer.read" ] } ] } }, "/internal-transfers/idempotencyKey/{idempotencyKey}": { "get": { "tags": [ "Transfer between accounts" ], "summary": "Get a transfer by idempotency key", "description": "The same transfer, found by the x-idempotency-key you sent.", "operationId": "itIdem", "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "description": "The request idempotency key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "status": "LIQUIDATED", "transactionType": "INTERNAL", "payment": { "currency": "BRL", "amount": 100 } } } } } } }, "security": [ { "OAuth2": [ "internal-transfer.read" ] } ] } } }, "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "Troque clientId e clientSecret por um token em POST /oauth/token e mande Authorization: Bearer .", "flows": { "clientCredentials": { "tokenUrl": "https://bank.granseuk.com/api/v2/oauth/token", "scopes": { "account.read": "Permissão da chave: balance:read", "transactions.read": "Permissão da chave: transactions:read", "pix.read": "Permissão da chave: pix:read", "pix.write": "Permissão da chave: pix:send", "internal-transfer.write": "Permissão da chave: transfers:write", "internal-transfer.read": "Permissão da chave: transactions:read" } } } } } }, "security": [ { "OAuth2": [] } ] }