ACCOUNTS API

Accounts API Overview

Check the balance and statement, send Pix by key, follow each payment through to confirmation, get the receipt, transfer between accounts of the bank.

Base serverhttps://bank.granseuk.com/api/v2

API specifications

Download the specification file (OpenAPI) to import into Postman or Insomnia and test the requests.

Download YAML Download JSON

Send a Pix: from request to confirmation

Create a unique x-idempotency-key for the request (for example, your own order id) and keep it.
POST /pix/payments/dict with the Pix key, the amount and the x-idempotency-key. The response is 202 with status PROCESSING: the amount has already left the balance.
Wait for the outcome. With webhooks on, it arrives in the transfer notice (status LIQUIDATED) or cashout notice (status CANCELED). Without webhooks, call GET /pix/payments/idempotencyKey/{key} every few seconds until the status is no longer PROCESSING.
LIQUIDATED: done. The endToEndId is filled in and the receipt is at GET /pix/payments/receipt/{endToEndId}.
CANCELED: the Pix did not go out and the amount returns to the balance by itself. You may try again with a NEW key.
If the connection drops or times out, do NOT create another key: repeat the POST with the SAME x-idempotency-key (it returns the same payment, never paying twice) or look it up by key.

status	Meaning
`PROCESSING`	Accepted, on its way to the destination bank. Not final yet.
`LIQUIDATED`	Done: the money arrived.
`CANCELED`	It did not go out; the amount returned to the balance.

Sandbox (test environment)

Test the whole integration without moving real money. In the panel, under API, tap New key and choose Sandbox: the key is born with the sk_sbx_ prefix and a fake account holding R$ 10,000.00. Everything else matches production: the same base URL, the same token (POST /oauth/token with the sandbox key's Client ID and Client Secret), the same routes, the same fields and the same errors. Only the money is fake.

Sent Pix (POST /pix/payments/dict and /qrc): answers 202 already with the endToEndId and completes by itself in about 4 seconds (LIQUIDATED), with the transfer notice. The test fee is R$ 1.00.
Key falha@sandbox.test (EMAIL): the Pix is accepted and fails after about 4 seconds; the amount returns and the cashout notice arrives (CANCELED).
Key recusa@sandbox.test (EMAIL): refused immediately (400), nothing is debited.
Pix charge (PUT /cob/{txid}): stays ATIVA until you pay it with the sandbox command below; then it becomes CONCLUIDA, the balance goes up and the receive notice arrives. The pixCopiaECola of a sandbox charge can also be paid through POST /pix/payments/qrc.
Transfer between accounts (POST /internal-transfers): use document 111.444.777-35 (any name) as the test destination account.
Key lookup (GET /pix/keys/{key}) returns test data; naoexiste@sandbox.test answers 404.
Webhooks (POST /webhooks/{type}): apply only to the sandbox key and receive only test notices; they do not need to be enabled for the account.

Commands that play the part of the outside world (sandbox keys only; with a production key they answer 403):

Command	What it does
`POST /sandbox/cob/{txid}/pay`	Pays the charge: balance goes up, status CONCLUIDA, receive notice.
`POST /sandbox/pix/receive`	Simulates a Pix paid straight to your key. Body: { "amount": 25.50, "payer": "Someone" }.
`POST /sandbox/pix/payments/{endToEndId}/complete`	Speeds up the completion of a sent Pix (transfer notice).
`POST /sandbox/pix/payments/{endToEndId}/fail`	Forces a sent Pix to fail: the amount returns (cashout notice).
`POST /sandbox/balance/topup`	Adds fake balance. Body: { "amount": 500 }.
`GET /sandbox/info`	Lists these test keys and commands.

The sandbox is isolated: it does not use the real balance, does not go through the provider, and the endToEndIds it generates start with E99999999 (a bank that does not exist), so they are never mistaken for a real Pix. Test data is erased after 30 days. When everything works, create a production key and swap the Client ID and Client Secret: the code does not change.

API reference

Authentication

Get an access token

POST/oauth/token

Exchanges clientId and clientSecret for an access token (OAuth 2.0 client credentials). The token is valid for 1 hour; send it as Authorization: Bearer on every other route. Accepts JSON, a form body (client_id, client_secret, grant_type) or Authorization: Basic base64(clientId:clientSecret).

Request body

Field	Type	Description
`clientId`required	string	The first 14 characters of your API key (e.g. sk_live_AbCdEf) or the key id.
`clientSecret`required	string	The full API key (sk_live_…).
`grantType`required	string	Always client_credentials.
`scope`	string	Ignored: the token carries all of the key's permissions.

expiresAt is the expiry instant in Unix seconds.
The token stops working the moment its key is revoked.

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

Responses

Token issued

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

Account

Get the account balance

GET/accounts/balances

Balance in BRL. available is what can be spent now; blocked is what is on hold (by a bank review, for example).

Permission: account.read → balance:read

GET/accounts/balances

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

Responses

Success

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

List account transactions

GET/accounts/transactions

The account statement, newest first. Dates are inclusive (Sao Paulo time zone).

Permission: transactions.read → transactions:read

Query parameters

Field	Type	Description
`event_date_start`	date-time	Start date (ISO 8601; only the day is used).
`event_date_end`	date-time	End date (ISO 8601; only the day is used).
`page_offset`	integer	Start position (items to skip). Default 0.
`page_limit`	integer	Items per page, up to 100. Default 25.

creditDebitType: CREDIT is money in, DEBIT is money out. transactionAmount.available and amount carry the same value.

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'

Responses

Success

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

List the account Pix keys

GET/accounts/keys

The Pix keys the bank generated for your account. Whoever pays a key chooses the amount in their bank app. Keys are created in the bank panel; this API is read-only.

Permission: pix.read → pix:read

GET/accounts/keys

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

Responses

Success

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

Start a Pix payment by Pix key

POST/pix/payments/dict

Sends a Pix to a key (CPF, CNPJ, e-mail, phone or EVP, the random key). The amount is debited right away and the payment is accepted for processing (202). The outcome (LIQUIDATED or CANCELED) comes from the lookup by endToEndId or by idempotency key. If it is refused, the amount returns to the account.

Permission: pix.write → pix:send

Headers

Field	Type	Description
`x-idempotency-key`required	string	Unique request identifier (1 to 50 letters and digits). Repeating the same key returns the SAME payment, never paying twice.

Request body

Field	Type	Description
`pixKey`required	string	The destination Pix key.
`pixKeyType`required	string	CPF \| CNPJ \| EMAIL \| PHONE \| EVP
`payment.amount`required	number	Amount in BRL, up to 2 decimals.
`payment.currency`	string	BRL.
`description`	string	Pix text, up to 140 characters.
`priority, paymentFlow, creditorDocument, expiration, endToEndId, ispbDeny`	—	Accepted and ignored (the bank chooses).

endToEndId may be null in the 202: it appears as soon as the Pix goes on to the destination bank. Look it up by idempotency key or by transactionId.
id is a stable number; to look it up use endToEndId or 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"}'

Responses

Accepted

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

Get a Pix by end-to-end id

GET/pix/payments/{endToEndId}

The full payment. Accepts the Pix endToEndId or the transactionId returned on creation. 404 if it is not a payment of your account.

Permission: pix.read → pix:read

Path parameters

Field	Type	Description
`endToEndId`required	string	The Pix endToEndId (or the transactionId).

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

GET/pix/payments/{endToEndId}

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

Responses

Success

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

Get a Pix by idempotency key

GET/pix/payments/idempotencyKey/{idempotencyKey}

The same payment, found by the x-idempotency-key you sent. Use it after a timeout to find out whether the request arrived.

Permission: pix.read → pix:read

Path parameters

Field	Type	Description
`idempotencyKey`required	string	The request idempotency key.

GET/pix/payments/idempotencyKey/{idempotencyKey}

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

Responses

Success

{
  "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 the Pix receipt as a PDF

GET/pix/payments/receipt/{endToEndId}

The payment receipt as a base64-encoded PDF (with the bank's branding). Accepts the endToEndId or the transactionId.

Permission: pix.read → pix:read

Path parameters

Field	Type	Description
`endToEndId`required	string	The Pix endToEndId (or the transactionId).

GET/pix/payments/receipt/{endToEndId}

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

Responses

Success

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

Look up a Pix key

GET/pix/keys/{key}

What the DICT says about any Pix key: name, document (masked by the DICT itself) and bank. Use it to confirm the recipient before sending. If the bank's provider does not query the DICT, it answers 501 not_supported.

Permission: pix.read → pix:read

Path parameters

Field	Type	Description
`key`required	string	The Pix key (CPF, CNPJ, e-mail, phone or random).

GET/pix/keys/{key}

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

Responses

Success

{
  "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 between accounts

Create a transfer between accounts

POST/internal-transfers

Transfers to another account at this same bank, instantly and without going through Pix. The destination account is found by the holder's document (CPF or CNPJ), and the name you send must match the account: if any check fails, nothing is transferred. Repeating the same x-idempotency-key returns the same transfer.

Permission: internal-transfer.write → transfers:write

Headers

Field	Type	Description
`x-idempotency-key`required	string	Unique request identifier (1 to 50 letters and digits).

Request body

Field	Type	Description
`creditorAccount.document`required	string	CPF or CNPJ of the destination account holder.
`creditorAccount.name`required	string	Holder name. Must match the account.
`creditorAccount.number`	string	Optional: the destination account id, as an extra check.
`payment.amount`required	number	Amount in BRL, up to 2 decimals.
`remittanceInformation`	string	Description, up to 200 characters.
`creditorAccount.issuer, creditorAccount.accountType, paymentFlow`	—	Accepted and ignored.

It does not go through Pix: the transfer is created already settled (LIQUIDATED) and endToEndId is null.

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

Responses

Accepted

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

Get a transfer between accounts

GET/internal-transfers/{endToEndId}

The transfer by endToEndId (when there is one) or by the transactionId returned on creation.

Permission: internal-transfer.read → transactions:read

Path parameters

Field	Type	Description
`endToEndId`required	string	The endToEndId or the transactionId.

GET/internal-transfers/{endToEndId}

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

Responses

Success

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

Get a transfer by idempotency key

GET/internal-transfers/idempotencyKey/{idempotencyKey}

The same transfer, found by the x-idempotency-key you sent.

Permission: internal-transfer.read → transactions:read

Path parameters

Field	Type	Description
`idempotencyKey`required	string	The request idempotency key.

GET/internal-transfers/idempotencyKey/{idempotencyKey}

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

Responses

Success

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