{ "openapi": "3.0.3", "info": { "title": "QR Code API", "version": "2.0.0", "description": "QR Code API Overview\n\nCreate Pix charges with a dynamic QR code (txid), show the pixCopiaECola to the payer, confirm the payment and receive the money in the account." }, "servers": [ { "url": "https://bank.granseuk.com/api/v2" } ], "tags": [ { "name": "Authentication" }, { "name": "Pix charges" } ], "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": [] } }, "/cob/{txid}": { "put": { "tags": [ "Pix charges" ], "summary": "Create an immediate charge with a txid", "description": "Creates a Pix charge (dynamic QR) with the txid you choose: 26 to 35 letters and digits. Repeating the PUT with the same txid returns the same charge. Each bank sets a minimum amount per charge (below it: 400 below_limit, with the minimum in the message).", "operationId": "cobPut", "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "26 to 35 letters and digits.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "object", "properties": { "original": { "type": "string", "description": "Amount in BRL as a dot-decimal string (\"49.90\")." } } }, "calendario": { "type": "object", "properties": { "expiracao": { "type": "integer", "description": "Validity in seconds, 60 to 2592000. Default 86400." } } }, "solicitacaoPagador": { "type": "string", "description": "Text shown to the payer, up to 140 characters." } } }, "example": { "calendario": { "expiracao": 3600 }, "devedor": { "cpf": "12345678909", "nome": "Fulano de Tal" }, "valor": { "original": "49.90" }, "solicitacaoPagador": "Pedido 1042" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "txid": "ABC123def456GHI789jkl012MNO345", "id": "0b6c2a0e-91a1-4e0e-8b73-8a0b6d3f1d22", "revisao": 0, "status": "ATIVA", "calendario": { "criacao": "2026-10-20T14:05:00.000Z", "expiracao": 3600 }, "devedor": { "nome": "Fulano de Tal", "cpf": "12345678909" }, "valor": { "original": "49.90", "modalidadeAlteracao": 0 }, "chave": null, "loc": null, "location": null, "solicitacaoPagador": "Pedido 1042", "infoAdicionais": [], "pixCopiaECola": "00020126…6304ABCD" } } } } }, "security": [ { "OAuth2": [ "cob.write" ] } ] }, "get": { "tags": [ "Pix charges" ], "summary": "Get an immediate charge", "description": "The charge state. When paid, status is CONCLUIDA and the pix list carries the endToEndId. When money arrives, always confirm with this call; do not rely on an external notice alone.\n\nstatus: ATIVA (waiting), CONCLUIDA (paid), REMOVIDA_PELO_USUARIO_RECEBEDOR (cancelled), REMOVIDA_PELO_PSP (expired).", "operationId": "cobGet", "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "The charge txid.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "txid": "ABC123def456GHI789jkl012MNO345", "status": "CONCLUIDA", "valor": { "original": "49.90" }, "pix": [ { "endToEndId": "E3187249520261020184600abcdEFGH12345", "valor": "49.90", "horario": "2026-10-20T14:07:41.000Z" } ] } } } }, "404": { "description": "Charge not found", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Cobranca nao encontrada", "instance": "/api/v2/cob/{txid}", "statusCode": 404, "error": "not_found", "message": "Cobranca nao encontrada" } } } } }, "security": [ { "OAuth2": [ "cob.read" ] } ] } }, "/cob": { "post": { "tags": [ "Pix charges" ], "summary": "Create an immediate charge (generated txid)", "description": "Same as the PUT, but the bank generates the txid and returns it in the response.", "operationId": "cobPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "object", "properties": { "original": { "type": "string", "description": "Amount in BRL as a dot-decimal string (\"49.90\")." } } }, "calendario": { "type": "object", "properties": { "expiracao": { "type": "integer", "description": "Validity in seconds, 60 to 2592000. Default 86400." } } } } }, "example": { "calendario": { "expiracao": 3600 }, "valor": { "original": "49.90" }, "solicitacaoPagador": "Pedido 1042" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "txid": "5f2c9d8e7a6b4c3d2e1f0a9b8c7d6e5f", "id": "0b6c2a0e-91a1-4e0e-8b73-8a0b6d3f1d22", "revisao": 0, "status": "ATIVA", "calendario": { "criacao": "2026-10-20T14:05:00.000Z", "expiracao": 3600 }, "devedor": { "nome": "Fulano de Tal", "cpf": "12345678909" }, "valor": { "original": "49.90", "modalidadeAlteracao": 0 }, "chave": null, "loc": null, "location": null, "solicitacaoPagador": "Pedido 1042", "infoAdicionais": [], "pixCopiaECola": "00020126…6304ABCD" } } } } }, "security": [ { "OAuth2": [ "cob.write" ] } ] } } }, "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": { "cob.write": "Permissão da chave: pix:write", "cob.read": "Permissão da chave: pix:read" } } } } } }, "security": [ { "OAuth2": [] } ] }