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.

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