API CONTAS

Visão Geral da API Contas

Consulte o saldo e o extrato, envie Pix por chave, acompanhe cada pagamento até a confirmação, tire o comprovante, transfira entre contas do banco.

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

Enviar Pix: do pedido à confirmação

Crie uma x-idempotency-key única para o pedido (por exemplo, o id do seu pedido) e guarde-a.
POST /pix/payments/dict com a chave Pix, o valor e a x-idempotency-key. A resposta é 202 com status PROCESSING: o valor já saiu do saldo.
Espere o desfecho. Com webhooks ativos, ele chega no aviso transfer (status LIQUIDATED) ou cashout (status CANCELED). Sem webhook, consulte GET /pix/payments/idempotencyKey/{chave} a cada poucos segundos até o status deixar de ser PROCESSING.
LIQUIDATED: concluído. O endToEndId vem preenchido e o comprovante está em GET /pix/payments/receipt/{endToEndId}.
CANCELED: o Pix não saiu e o valor volta ao saldo sozinho. Pode tentar de novo com uma chave NOVA.
Se a conexão cair ou der timeout, NÃO crie outra chave: repita o POST com a MESMA x-idempotency-key (devolve o mesmo pagamento, sem pagar duas vezes) ou consulte pela chave.

status	Significado
`PROCESSING`	Aceito, a caminho do banco de destino. Ainda não é definitivo.
`LIQUIDATED`	Concluído: o dinheiro chegou.
`CANCELED`	Não saiu; o valor voltou ao saldo.

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

Conta

Consultar saldo da conta

GET/accounts/balances

Saldo em reais. available é o que pode ser gasto agora; blocked, o que está retido (por uma análise do banco, por exemplo).

Permissão: account.read → balance:read

GET/accounts/balances

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

Respostas

Sucesso

{
  "data": [
    {
      "eventDate": "2026-10-20T14:00:00.000Z",
      "balanceAmount": {
        "currency": "BRL",
        "available": 1234.56,
        "blocked": 0,
        "overdraft": 0
      }
    }
  ]
}

Consultar transações da conta

GET/accounts/transactions

O extrato da conta, mais recente primeiro. As datas são inclusivas (fuso de São Paulo).

Permissão: transactions.read → transactions:read

Parâmetros de consulta

Campo	Tipo	Descrição
`event_date_start`	date-time	Data inicial (ISO 8601; só o dia é usado).
`event_date_end`	date-time	Data final (ISO 8601; só o dia é usado).
`page_offset`	integer	Posição inicial (itens a pular). Padrão 0.
`page_limit`	integer	Itens por página, até 100. Padrão 25.

creditDebitType: CREDIT é entrada, DEBIT é saída. transactionAmount.available e amount trazem o mesmo valor.

GET/accounts/transactions

curl -X GET 'https://bank.granseuk.com/api/v2/accounts/transactions?event_date_start=2026-10-01&event_date_end=2026-10-20' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

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

Listar chaves Pix da conta

GET/accounts/keys

As chaves Pix que o banco gerou para a sua conta. Quem paga uma chave escolhe o valor no aplicativo do banco dele. As chaves são criadas pelo painel do banco; por esta API só se lê.

Permissão: pix.read → pix:read

GET/accounts/keys

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

Respostas

Sucesso

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

Pix

Iniciar pagamento Pix por chave Pix

POST/pix/payments/dict

Envia um Pix para uma chave (CPF, CNPJ, e-mail, telefone ou EVP, a chave aleatória). O valor é debitado na hora e o pagamento é aceito para processamento (202). O desfecho (LIQUIDATED ou CANCELED) vem na consulta pelo endToEndId ou pela chave de idempotência. Se for recusado, o valor volta para a conta.

Permissão: pix.write → pix:send

Cabeçalhos

Campo	Tipo	Descrição
`x-idempotency-key`obrigatório	string	Identificador único do pedido (1 a 50 letras e números). Repetir a mesma chave devolve o MESMO pagamento, sem pagar duas vezes.

Corpo da requisição

Campo	Tipo	Descrição
`pixKey`obrigatório	string	A chave Pix de destino.
`pixKeyType`obrigatório	string	CPF \| CNPJ \| EMAIL \| PHONE \| EVP
`payment.amount`obrigatório	number	Valor em reais, até 2 casas decimais.
`payment.currency`	string	BRL.
`description`	string	Texto do Pix, até 140 caracteres.
`priority, paymentFlow, creditorDocument, expiration, endToEndId, ispbDeny`	—	Aceitos e ignorados (o banco escolhe).

endToEndId pode vir nulo no 202: ele aparece assim que o Pix segue para o banco de destino. Consulte pela chave de idempotência ou pelo transactionId.
id é um número estável; para consultar use endToEndId ou transactionId.

POST/pix/payments/dict

curl -X POST 'https://bank.granseuk.com/api/v2/pix/payments/dict' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'x-idempotency-key: pedido1042' \
  -H 'Content-Type: application/json' \
  -d '{"pixKey":"fulano@exemplo.com","pixKeyType":"EMAIL","payment":{"currency":"BRL","amount":25.5},"description":"Repasse pedido 1042"}'

Respostas

Aceito

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

Consultar Pix por end-to-end-id

GET/pix/payments/{endToEndId}

O pagamento completo. Aceita o endToEndId do Pix ou o transactionId devolvido ao criar. 404 se não for um pagamento da sua conta.

Permissão: pix.read → pix:read

Parâmetros do caminho

Campo	Tipo	Descrição
`endToEndId`obrigatório	string	O endToEndId do Pix (ou o transactionId).

status: PROCESSING, LIQUIDATED, CANCELED, REFUNDED ou WAITING_APPROVAL.

GET/pix/payments/{endToEndId}

curl -X GET 'https://bank.granseuk.com/api/v2/pix/payments/E3187249520261020184600abcdEFGH12345' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "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": []
  }
}

Consultar Pix por chave de idempotência

GET/pix/payments/idempotencyKey/{idempotencyKey}

O mesmo pagamento, achado pela x-idempotency-key que você mandou. Use depois de um timeout para saber se o pedido chegou.

Permissão: pix.read → pix:read

Parâmetros do caminho

Campo	Tipo	Descrição
`idempotencyKey`obrigatório	string	A chave de idempotência do pedido.

GET/pix/payments/idempotencyKey/{idempotencyKey}

curl -X GET 'https://bank.granseuk.com/api/v2/pix/payments/idempotencyKey/pedido1042' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "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": []
  }
}

Obter comprovante do Pix em PDF

GET/pix/payments/receipt/{endToEndId}

O comprovante do pagamento, em PDF codificado em base64 (com a marca do banco). Aceita o endToEndId ou o transactionId.

Permissão: pix.read → pix:read

Parâmetros do caminho

Campo	Tipo	Descrição
`endToEndId`obrigatório	string	O endToEndId do Pix (ou o transactionId).

GET/pix/payments/receipt/{endToEndId}

curl -X GET 'https://bank.granseuk.com/api/v2/pix/payments/receipt/E3187249520261020184600abcdEFGH12345' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "data": {
    "pdf": "JVBERi0xLjQK…"
  }
}

Consultar dados de uma chave Pix

GET/pix/keys/{key}

O que o DICT diz de uma chave Pix qualquer: nome, documento (mascarado pelo próprio DICT) e banco. Use para confirmar o destinatário antes de enviar. Se a provedora do banco não consulta o DICT, responde 501 not_supported.

Permissão: pix.read → pix:read

Parâmetros do caminho

Campo	Tipo	Descrição
`key`obrigatório	string	A chave Pix (CPF, CNPJ, e-mail, telefone ou aleatória).

GET/pix/keys/{key}

curl -X GET 'https://bank.granseuk.com/api/v2/pix/keys/{key}' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "name": "Fulano de Tal",
  "tradeName": null,
  "keyType": "EMAIL",
  "key": "fulano@exemplo.com",
  "document": "***.456.789-**",
  "ispb": "00000000",
  "ispb_reduced_name": "Banco Exemplo",
  "endToEndId": null
}

Transferência entre contas

Criar transferência entre contas

POST/internal-transfers

Transfere para outra conta deste mesmo banco, na hora e sem passar pelo Pix. A conta de destino é achada pelo documento (CPF ou CNPJ) do titular, e o nome informado precisa bater com o da conta: se qualquer conferência falhar, nada é transferido. Repetir a mesma x-idempotency-key devolve a mesma transferência.

Permissão: internal-transfer.write → transfers:write

Cabeçalhos

Campo	Tipo	Descrição
`x-idempotency-key`obrigatório	string	Identificador único do pedido (1 a 50 letras e números).

Corpo da requisição

Campo	Tipo	Descrição
`creditorAccount.document`obrigatório	string	CPF ou CNPJ do titular da conta de destino.
`creditorAccount.name`obrigatório	string	Nome do titular. Precisa bater com o da conta.
`creditorAccount.number`	string	Opcional: o id da conta de destino, para conferir.
`payment.amount`obrigatório	number	Valor em reais, até 2 casas decimais.
`remittanceInformation`	string	Descrição, até 200 caracteres.
`creditorAccount.issuer, creditorAccount.accountType, paymentFlow`	—	Aceitos e ignorados.

Não passa pelo Pix: a transferência já nasce liquidada (LIQUIDATED) e o endToEndId vem nulo.

POST/internal-transfers

curl -X POST 'https://bank.granseuk.com/api/v2/internal-transfers' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'x-idempotency-key: pedido1042' \
  -H 'Content-Type: application/json' \
  -d '{"creditorAccount":{"document":"12345678909","name":"Fulano de Tal","number":"","accountType":"TRAN"},"payment":{"currency":"BRL","amount":100},"remittanceInformation":"Acerto do pedido 1042"}'

Respostas

Aceita

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

Consultar transferência entre contas

GET/internal-transfers/{endToEndId}

A transferência pelo endToEndId (quando existir) ou pelo transactionId devolvido ao criar.

Permissão: internal-transfer.read → transactions:read

Parâmetros do caminho

Campo	Tipo	Descrição
`endToEndId`obrigatório	string	O endToEndId ou o transactionId.

GET/internal-transfers/{endToEndId}

curl -X GET 'https://bank.granseuk.com/api/v2/internal-transfers/E3187249520261020184600abcdEFGH12345' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "data": {
    "id": 218394857401,
    "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10",
    "status": "LIQUIDATED",
    "transactionType": "INTERNAL",
    "payment": {
      "currency": "BRL",
      "amount": 100
    }
  }
}

Consultar transferência por chave de idempotência

GET/internal-transfers/idempotencyKey/{idempotencyKey}

A mesma transferência, achada pela x-idempotency-key que você mandou.

Permissão: internal-transfer.read → transactions:read

Parâmetros do caminho

Campo	Tipo	Descrição
`idempotencyKey`obrigatório	string	A chave de idempotência do pedido.

GET/internal-transfers/idempotencyKey/{idempotencyKey}

curl -X GET 'https://bank.granseuk.com/api/v2/internal-transfers/idempotencyKey/pedido1042' \
  -H 'Authorization: Bearer SEU_TOKEN'

Respostas

Sucesso

{
  "data": {
    "id": 218394857401,
    "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10",
    "status": "LIQUIDATED",
    "transactionType": "INTERNAL",
    "payment": {
      "currency": "BRL",
      "amount": 100
    }
  }
}