API QRCODE

Visão Geral da API QRCode

Crie cobranças Pix com QR Code dinâmico (txid), mostre o pixCopiaECola ao pagador, confirme o pagamento e receba o dinheiro na conta.

Servidor basehttps://bank.granseuk.com/api/v2

Especificações da API

Baixe o arquivo da especificação (OpenAPI) para importar no Postman ou no Insomnia e testar as requisições.

Baixar YAML Baixar JSON

Receber Pix: da cobrança à confirmação

PUT /cob/{txid} (ou POST /cob) com o valor e a validade. A resposta traz o pixCopiaECola: mostre-o (ou o QR Code dele) ao pagador.
Quando o pagador paga, o dinheiro entra no saldo na hora e a cobrança vira CONCLUIDA. Com webhooks ativos, chega o aviso receive; sem webhook, consulte GET /cob/{txid} até o status ser CONCLUIDA (a lista pix traz o endToEndId).
Libere o pedido só com a cobrança CONCLUIDA. ATIVA é aguardando pagamento; REMOVIDA_PELO_PSP é cobrança vencida.
Pix pago direto numa chave da conta (GET /accounts/keys) não tem cobrança: aparece como CREDIT em GET /accounts/transactions e no aviso receive.
Para conferir o dinheiro, use GET /accounts/balances (disponível) e GET /accounts/transactions (extrato).

Referência da API

Autenticação

Obter token de acesso

POST/oauth/token

Troca o clientId e o clientSecret por um token de acesso (OAuth 2.0, client credentials). O token vale 1 hora; use-o em Authorization: Bearer nas demais rotas. Aceita JSON, formulário (client_id, client_secret, grant_type) ou Authorization: Basic base64(clientId:clientSecret).

Corpo da requisição

Campo	Tipo	Descrição
`clientId`obrigatório	string	Os 14 primeiros caracteres da sua chave de API (ex.: sk_live_AbCdEf) ou o id da chave.
`clientSecret`obrigatório	string	A chave de API completa (sk_live_…).
`grantType`obrigatório	string	Sempre client_credentials.
`scope`	string	Ignorado: o token carrega todas as permissões da chave.

expiresAt é o instante de expiração em segundos Unix.
O token deixa de valer na hora em que a chave é revogada.

POST/oauth/token

curl -X POST 'https://bank.granseuk.com/api/v2/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{"clientId":"sk_live_AbCdEf","clientSecret":"sk_live_AbCdEf…chave-completa","grantType":"client_credentials"}'

Respostas

Token emitido

{
  "tokenType": "Bearer",
  "expiresAt": 1792529169,
  "refreshExpiresIn": 0,
  "notBeforePolicy": 0,
  "accessToken": "v2t_Zk3q…",
  "scope": "account.read transactions.read pix.read cob.read cob.write pix.write"
}

Cobranças Pix

Criar cobrança imediata com txid

PUT/cob/{txid}

Cria uma cobrança Pix (QR dinâmico) com o txid que você escolhe: 26 a 35 letras e números. Repetir o PUT com o mesmo txid devolve a mesma cobrança. Cada banco define um valor mínimo por cobrança (abaixo dele: 400 below_limit, com o mínimo na mensagem).

Permissão: cob.write → pix:write

Parâmetros do caminho

Campo	Tipo	Descrição
`txid`obrigatório	string	26 a 35 letras e números.

Corpo da requisição

Campo	Tipo	Descrição
`valor.original`obrigatório	string	Valor em reais, texto com ponto ("49.90").
`calendario.expiracao`	integer	Validade em segundos, de 60 a 2592000. Padrão 86400.
`devedor.nome, devedor.cpf, devedor.cnpj`	string	Quem vai pagar (opcional).
`solicitacaoPagador`	string	Texto mostrado ao pagador, até 140 caracteres.

PUT/cob/{txid}

curl -X PUT 'https://bank.granseuk.com/api/v2/cob/ABC123def456GHI789jkl012MNO345' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"calendario":{"expiracao":3600},"devedor":{"cpf":"12345678909","nome":"Fulano de Tal"},"valor":{"original":"49.90"},"solicitacaoPagador":"Pedido 1042"}'

Respostas

Criada

{
  "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"
}

Criar cobrança imediata (txid gerado)

POST/cob

Igual ao PUT, mas o banco gera o txid e devolve na resposta.

Permissão: cob.write → pix:write

Corpo da requisição

Campo	Tipo	Descrição
`valor.original`obrigatório	string	Valor em reais, texto com ponto ("49.90").
`calendario.expiracao`	integer	Validade em segundos, de 60 a 2592000. Padrão 86400.
`devedor, solicitacaoPagador`	object \| string	Como no PUT.

POST/cob

curl -X POST 'https://bank.granseuk.com/api/v2/cob' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"calendario":{"expiracao":3600},"valor":{"original":"49.90"},"solicitacaoPagador":"Pedido 1042"}'

Respostas

Criada

{
  "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"
}

Consultar cobrança imediata

GET/cob/{txid}

O estado da cobrança. Quando paga, status é CONCLUIDA e a lista pix traz o endToEndId. Ao receber, confirme sempre por esta consulta; não confie só em um aviso externo.

Permissão: cob.read → pix:read

Parâmetros do caminho

Campo	Tipo	Descrição
`txid`obrigatório	string	O txid da cobrança.

status: ATIVA (aguardando), CONCLUIDA (paga), REMOVIDA_PELO_USUARIO_RECEBEDOR (cancelada), REMOVIDA_PELO_PSP (expirada).

GET/cob/{txid}

curl -X GET 'https://bank.granseuk.com/api/v2/cob/ABC123def456GHI789jkl012MNO345' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "txid": "ABC123def456GHI789jkl012MNO345",
  "status": "CONCLUIDA",
  "valor": {
    "original": "49.90"
  },
  "pix": [
    {
      "endToEndId": "E3187249520261020184600abcdEFGH12345",
      "valor": "49.90",
      "horario": "2026-10-20T14:07:41.000Z"
    }
  ]
}