# API v2

Integre Pix, saldo, extrato, cobranças e avisos no seu sistema com um token e poucas chamadas.

URL base: https://bank.granseuk.com/api/v2

## Visão geral

URL base: https://bank.granseuk.com/api/v2

Ativo neste banco:

- Enviar Pix para uma chave
- Receber Pix por cobrança (QR dinâmico com txid)
- Receber Pix direto nas chaves da conta
- Saldo, extrato e comprovante em PDF
- Transferência entre contas do banco

A API v2 reúne o que você precisa para integrar Pix, saldo, extrato, cobranças e avisos no seu sistema, com o desenho das APIs de Pix mais usadas no mercado: um token, caminhos curtos e respostas previsíveis. Se você já integra com outra provedora de Pix, em geral basta trocar a URL base e as credenciais. As regras de dinheiro são as mesmas da API v1: saldo, tarifas, limites, idempotência, certificado de cliente (mTLS) e as funções que o seu banco desligou.

- Valores em reais, como número (25.5) nos pagamentos, saldo e extrato; como texto ("49.90") nas cobranças, como no padrão BACEN.
- Datas em ISO 8601 (UTC).
- Estados de pagamento: PROCESSING, LIQUIDATED, CANCELED, REFUNDED, WAITING_APPROVAL.
- Estados de cobrança: ATIVA, CONCLUIDA, REMOVIDA_PELO_USUARIO_RECEBEDOR, REMOVIDA_PELO_PSP.
- A API v1 (em /docs) continua igual e funciona ao mesmo tempo.

## Comece em 3 passos

- No painel do banco, abra API, toque em Nova chave, escolha Produção e use o atalho "Integração completa (receber e enviar Pix)" (ele marca saldo, extrato, consultas, cobrar por Pix, enviar Pix e transferir). Ao criar, o painel mostra o Client ID, o Client Secret (a chave, que aparece uma vez: guarde-a) e a URL base.
- Troque as credenciais por um token: POST /oauth/token (clientId = 14 primeiros caracteres da chave, clientSecret = a chave).
- Chame as rotas com Authorization: Bearer <accessToken>. Em todo pagamento, mande x-idempotency-key.

## Autenticação e permissões

Use o token de 1 hora do /oauth/token em Authorization: Bearer. Peça outro quando faltar pouco ou ao receber 401. A chave sk_ direta no Bearer também funciona. A chave define o que o token pode fazer: o campo scope do pedido é ignorado.

| Escopo | Permissão da sua chave | Rotas |
| --- | --- | --- |
| account.read | balance:read | GET /accounts/balances |
| transactions.read | transactions:read | GET /accounts/transactions |
| pix.read / cob.read | pix:read | GET /accounts/keys, GET /pix/payments/*, GET /cob/{txid} |
| pix.write | pix:send | POST /pix/payments/dict |
| cob.write | pix:write | PUT /cob/{txid}, POST /cob |
| internal-transfer.write | transfers:write | POST /internal-transfers |
| internal-transfer.read | transactions:read | GET /internal-transfers/{endToEndId}, GET /internal-transfers/idempotencyKey/{key} |

Certificado de cliente (mTLS): opcional por padrão. Se o seu banco ligou a trava para a sua conta, a chamada precisa dele (403 certificate_required sem ele).

## Outras funções da sua conta

Além das rotas desta página, o seu banco liberou estas funções na API v1. O mesmo token (Authorization: Bearer) vale nelas; a referência completa de cada uma está na documentação da v1.

| Função | Rotas | Permissão da chave |
| --- | --- | --- |
| Transferência entre contas (também na v2: /internal-transfers) | POST /v1/transfers | transfers:write |
| Links de pagamento | POST /v1/payment-links, GET /v1/payment-links | pix:write |
| Split de recebimentos | GET/PUT /v1/split, GET /v1/split/lookup, GET /v1/split/history | split:read, split:write |
| Split para chave Pix | PUT /v1/split/pix | split:write |
| Folha de pagamento | /v1/payroll/* | payroll:read, payroll:write |

Referência completa: /docs (API v1).

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

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

## Idempotência

Todo pagamento exige o cabeçalho x-idempotency-key (1 a 50 letras e números). Repetir a mesma chave devolve o MESMO pagamento, sem pagar duas vezes. Se a conexão cair e você não souber se o pedido chegou, repita com a mesma chave ou consulte GET /pix/payments/idempotencyKey/{chave}.

## Erros

    {
      "type": "onz-0008",
      "title": "Invalid request",
      "status": 400,
      "detail": "Saldo insuficiente",
      "instance": "/api/v2/pix/payments/dict",
      "statusCode": 400,
      "error": "insufficient_funds",
      "message": "Saldo insuficiente"
    }

| type | title | Quando |
| --- | --- | --- |
| onz-0001 | Invalid credentials | clientId ou clientSecret inválidos (401) |
| onz-0002 | Invalid params | Campo faltando ou inválido; a mensagem diz qual (400) |
| onz-0003 | Invalid token | Token ausente, inválido, expirado ou chave revogada (401) |
| onz-0004 | Internal server error | Falha nossa; guarde o ref (500) |
| onz-0005 | Server shutting down | Sistema ocupado: repita em instantes (503) |
| onz-0006 | Invalid token role | A chave não tem a permissão da rota, o banco desligou a função ou falta o certificado mTLS (403) |
| onz-0007 | Invalid pix entry | Chave Pix inválida (400) |
| onz-0008 | Invalid request | Uma regra de negócio recusou (saldo, limite, destinatário…), limite de chamadas ou rota que o banco não tem. Nada foi debitado (400, 429, 501) |
| onz-0009 | Pix not found | Pagamento, cobrança ou transferência não encontrados nesta conta (404) |
| onz-0010 | Invalid QR code | QR Code inválido ou com valor diferente do informado (400) |
| onz-0011 | Invalid idempotency key | Faltou ou é inválida a x-idempotency-key (400) |
| onz-0012 | Webhook not found | Webhook não encontrado (404) |

O corpo do erro traz type (o código onz-XXXX da tabela), title, status, detail e instance, e também statusCode, error (o código detalhado, como insufficient_funds) e message. Decida pelo código HTTP e pelo type; o campo error diz o motivo exato. Em erro 5xx vem também um ref: guarde-o ao falar com o suporte.

## Migrando de outra provedora

- Troque a URL base por https://bank.granseuk.com/api/v2.
- Troque clientId e clientSecret pelos da sua chave (veja Autenticação).
- POST /pix/payments/dict responde 202 com { endToEndId, eventDate, id, payment, type }. O endToEndId pode vir nulo até o Pix seguir; consulte pela chave de idempotência.
- GET /pix/payments/{endToEndId} devolve { data: {...} }. Também aceita o transactionId.
- O campo id é um número estável, mas não serve para consultar: use endToEndId ou transactionId.
- Os códigos de erro (type onz-XXXX) e os nomes dos escopos que o token devolve (pix.write, cob.write, account.read…) são os mesmos; ao criar a chave no painel, as permissões têm nomes próprios (pix:send, pix:write…): veja a tabela de permissões.

## O que ainda não existe

- Criação de chave Pix por API (as chaves são criadas no painel) e devolução de Pix recebido.
- Boletos (/billets) e TED neste formato.
- Cobrança com vencimento (/cobv), recorrente (/cobr) e Pix Automático.
- Chave de sandbox (sk_sbx_) não troca token; use a v1 para testar sem dinheiro real.

Rotas deste padrão que ainda não existem respondem 501 not_supported, com a explicação (por exemplo, POST /accounts/keys).

## Integrando com IA

Toda esta documentação, em texto puro, está em /docs/v2/llms.txt (acrescente ?lang=en para inglês). Cole o conteúdo no seu assistente e peça o código.

## Referência da API

### Autenticação

#### POST /oauth/token — Obter token de acesso

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

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

**Exemplo de código (curl)**

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

**201** — 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"
    }

**401** — clientId ou clientSecret inválidos, ou chave revogada/expirada

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

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

### Conta

#### GET /accounts/balances — Consultar saldo da conta

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

**Exemplo de código (curl)**

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

**200** — Sucesso

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

#### GET /accounts/transactions — Consultar transações da conta

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

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

**Exemplo de código (curl)**

    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'

**200** — 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"
          }
        }
      ]
    }

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

#### GET /accounts/keys — Listar chaves Pix da conta

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

**Exemplo de código (curl)**

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

**200** — 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

#### POST /pix/payments/dict — Iniciar pagamento Pix por chave Pix

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

- `x-idempotency-key` (string, obrigatório): 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**

- `pixKey` (string, obrigatório): A chave Pix de destino.
- `pixKeyType` (string, obrigatório): CPF | CNPJ | EMAIL | PHONE | EVP
- `payment.amount` (number, obrigatório): 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).

**Exemplo de código (curl)**

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

**202** — 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
    }

**400** — Regra de negócio ou campo inválido (saldo, limite, chave inválida…). Nada foi debitado.

    {
      "type": "onz-0008",
      "title": "Invalid request",
      "status": 400,
      "detail": "Saldo insuficiente",
      "instance": "/api/v2/pix/payments/dict",
      "statusCode": 400,
      "error": "insufficient_funds",
      "message": "Saldo insuficiente"
    }

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

#### GET /pix/payments/{endToEndId} — Consultar Pix por end-to-end-id

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

- `endToEndId` (string, obrigatório): O endToEndId do Pix (ou o transactionId).

**Exemplo de código (curl)**

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

**200** — 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": []
      }
    }

**404** — Pagamento não encontrado nesta conta

    {
      "type": "onz-0009",
      "title": "Pix not found",
      "status": 404,
      "detail": "Pagamento nao encontrado",
      "instance": "/api/v2/pix/payments/{endToEndId}",
      "statusCode": 404,
      "error": "not_found",
      "message": "Pagamento nao encontrado"
    }

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

#### GET /pix/payments/idempotencyKey/{idempotencyKey} — Consultar Pix por chave de idempotência

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

- `idempotencyKey` (string, obrigatório): A chave de idempotência do pedido.

**Exemplo de código (curl)**

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

**200** — 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": []
      }
    }

#### GET /pix/payments/receipt/{endToEndId} — Obter comprovante do Pix em PDF

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

- `endToEndId` (string, obrigatório): O endToEndId do Pix (ou o transactionId).

**Exemplo de código (curl)**

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

**200** — Sucesso

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

**404** — Pagamento não encontrado nesta conta

    {
      "type": "onz-0009",
      "title": "Pix not found",
      "status": 404,
      "detail": "Pagamento nao encontrado",
      "instance": "/api/v2/pix/payments/receipt/{endToEndId}",
      "statusCode": 404,
      "error": "not_found",
      "message": "Pagamento nao encontrado"
    }

#### GET /pix/keys/{key} — Consultar dados de uma chave Pix

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

- `key` (string, obrigatório): A chave Pix (CPF, CNPJ, e-mail, telefone ou aleatória).

**Exemplo de código (curl)**

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

**200** — 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
    }

**404** — Chave não encontrada

    {
      "type": "onz-0009",
      "title": "Pix not found",
      "status": 404,
      "detail": "Chave Pix nao encontrada",
      "instance": "/api/v2/pix/keys/{key}",
      "statusCode": 404,
      "error": "not_found",
      "message": "Chave Pix nao encontrada"
    }

### Cobranças Pix

#### PUT /cob/{txid} — Criar cobrança imediata com 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**

- `txid` (string, obrigatório): 26 a 35 letras e números.

**Corpo da requisição**

- `valor.original` (string, obrigatório): 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.

**Exemplo de código (curl)**

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

**201** — 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"
    }

#### POST /cob — Criar cobrança imediata (txid gerado)

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

Permissão: cob.write → pix:write

**Corpo da requisição**

- `valor.original` (string, obrigatório): 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.

**Exemplo de código (curl)**

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

**201** — 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"
    }

#### GET /cob/{txid} — Consultar cobrança imediata

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

- `txid` (string, obrigatório): O txid da cobrança.

**Exemplo de código (curl)**

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

**200** — Sucesso

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

**404** — Cobrança não encontrada

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

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

### Transferência entre contas

#### POST /internal-transfers — Criar transferência entre contas

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

- `x-idempotency-key` (string, obrigatório): Identificador único do pedido (1 a 50 letras e números).

**Corpo da requisição**

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

**Exemplo de código (curl)**

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

**202** — 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
      }
    }

**404** — Não há conta neste banco com esse documento (recipient_not_found)

    {
      "type": "onz-0009",
      "title": "Pix not found",
      "status": 404,
      "detail": "Não há conta neste banco com esse documento",
      "instance": "/api/v2/internal-transfers",
      "statusCode": 404,
      "error": "recipient_not_found",
      "message": "Não há conta neste banco com esse documento"
    }

**400** — Nome diferente do titular (recipient_name_mismatch), saldo, limite… Nada foi transferido.

    {
      "type": "onz-0008",
      "title": "Invalid request",
      "status": 400,
      "detail": "O nome informado não confere com o titular da conta de destino. Nada foi transferido.",
      "instance": "/api/v2/internal-transfers",
      "statusCode": 400,
      "error": "recipient_name_mismatch",
      "message": "O nome informado não confere com o titular da conta de destino. Nada foi transferido."
    }

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

#### GET /internal-transfers/{endToEndId} — Consultar transferência entre contas

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

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

**Parâmetros do caminho**

- `endToEndId` (string, obrigatório): O endToEndId ou o transactionId.

**Exemplo de código (curl)**

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

**200** — Sucesso

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

#### GET /internal-transfers/idempotencyKey/{idempotencyKey} — Consultar transferência por chave de idempotência

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

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

**Parâmetros do caminho**

- `idempotencyKey` (string, obrigatório): A chave de idempotência do pedido.

**Exemplo de código (curl)**

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

**200** — Sucesso

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