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).

Sandbox (ambiente de testes)

Teste a integração inteira sem mover dinheiro de verdade. No painel, em API, toque em Nova chave e escolha Sandbox: a chave nasce com o prefixo sk_sbx_ e uma conta de mentira com R$ 10.000,00. O resto é igual à produção: a mesma URL base, o mesmo token (POST /oauth/token com o Client ID e o Client Secret da chave de sandbox), as mesmas rotas, os mesmos campos e os mesmos erros. Só o dinheiro é de mentira.

Pix enviado (POST /pix/payments/dict e /qrc): responde 202 já com o endToEndId e conclui sozinho em cerca de 4 segundos (LIQUIDATED), com o aviso transfer. A tarifa de teste é R$ 1,00.
Chave falha@sandbox.test (EMAIL): o Pix é aceito e falha em cerca de 4 segundos; o valor volta e chega o aviso cashout (CANCELED).
Chave recusa@sandbox.test (EMAIL): recusado na hora (400), nada é debitado.
Cobrança Pix (PUT /cob/{txid}): fica ATIVA até você pagá-la com o comando de sandbox abaixo; então vira CONCLUIDA, o saldo sobe e chega o aviso receive. O pixCopiaECola de uma cobrança de sandbox também pode ser pago por POST /pix/payments/qrc.
Transferência entre contas (POST /internal-transfers): use o documento 111.444.777-35 (qualquer nome) como conta de destino de teste.
Consulta de chave (GET /pix/keys/{chave}) devolve dados de teste; naoexiste@sandbox.test responde 404.
Webhooks (POST /webhooks/{tipo}): valem só para a chave de sandbox e recebem apenas os avisos de teste; não precisam estar liberados para a conta.

Comandos que fazem o papel do mundo de fora (só com chave de sandbox; com chave de produção respondem 403):

Comando	O que faz
`POST /sandbox/cob/{txid}/pay`	Paga a cobrança: saldo sobe, status CONCLUIDA, aviso receive.
`POST /sandbox/pix/receive`	Simula um Pix pago direto na sua chave. Corpo: { "amount": 25.50, "payer": "Fulano" }.
`POST /sandbox/pix/payments/{endToEndId}/complete`	Adianta a conclusão de um Pix enviado (aviso transfer).
`POST /sandbox/pix/payments/{endToEndId}/fail`	Força a falha de um Pix enviado: o valor volta (aviso cashout).
`POST /sandbox/balance/topup`	Soma saldo de mentira. Corpo: { "amount": 500 }.
`GET /sandbox/info`	Lista estas chaves e comandos de teste.

O sandbox é isolado: não usa o saldo real, não passa pela provedora e os endToEndId que ele gera começam com E99999999 (um banco que não existe), então nunca se confundem com um Pix de verdade. Os dados de teste são apagados depois de 30 dias. Quando tudo funcionar, crie uma chave de produção e troque o Client ID e o Client Secret: o código não muda.

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