Get Account Statement

Time	Status	User Agent
Retrieving recent requests…

Endpoint

GET /v3/account-statements/{account_branch_identifier}/{account_number}

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Path Parameters

Parameter	Type	Description	Required	Example
account_branch_identifier	String	Branch/agency number of the account	Yes	0001
account_number	String	Account number to retrieve statement	Yes	12345678-9

Query Parameters

Parameter	Type	Description	Required	Default	Example
start	DateTime	Start date and time for the transaction period (ISO 8601 format with timezone). Must be before `end`.	Yes	-	2026-04-01T00:00:00Z
end	DateTime	End date and time for the transaction period (ISO 8601 format with timezone). Must be after `start`.	Yes	-	2026-04-30T23:59:59Z
limit	Integer	Maximum number of transactions per page. Minimum: 1, Maximum: 100.	No	50	50
cursor	String	Opaque cursor token for pagination. Automatically provided in next/previous URLs. Do not construct manually.	No	-	opaque_cursor_xyz123
direction	String	Pagination direction when using cursor. Values: `next` (forward) or `previous` (backward). Required if cursor is set.	No	-	next

Request Examples

Get first page (initial request):

GET /v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Get first page with custom limit:

GET /v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z&limit=100
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Navigate to next page (use the complete URL from next field in response):

GET /v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z&limit=50&cursor=abc123def&direction=next
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Navigate to previous page (use the complete URL from previous field in response):

GET /v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z&limit=50&cursor=xyz789ghi&direction=previous
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b...

Response Details

{
  "worked": true,
  "next": "https://api.somossimpay.com.br/v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z&limit=50&cursor=next_cursor_token&direction=next",
  "previous": null,
  "results": [
    {
      "credit_or_debit": "CREDIT",
      "transaction_type": "PIX_CASHIN",
      "amount": 500.00,
      "date_time": "2026-04-15T14:30:00-03:00",
      "date_time_utc": "2026-04-15T17:30:00Z",
      "identification": "E123456789202604151430ABCD1234",
      "code_transaction": "E123456789202604151430ABCD1234",
      "code": 98765,
      "qr_code_id": null,
      "transaction_id": 5001,
      "tag_id": "invoice-4321",
      "end_to_end": "E123456789202604151430ABCD1234",
      "user_name": "João Silva",
      "user_document": "123.456.789-00",
      "user_agency": "0002",
      "user_account": "87654321-0"
    },
    {
      "credit_or_debit": "DEBIT",
      "transaction_type": "PIX_CASHOUT",
      "amount": 250.00,
      "date_time": "2026-04-14T10:15:00-03:00",
      "date_time_utc": "2026-04-14T13:15:00Z",
      "identification": "E987654321202604141015WXYZ9876",
      "code_transaction": "E987654321202604141015WXYZ9876",
      "code": 98764,
      "qr_code_id": 1234,
      "transaction_id": null,
      "tag_id": "payment-order-789",
      "end_to_end": "E987654321202604141015WXYZ9876",
      "user_name": "Maria Santos",
      "user_document": "987.654.321-00",
      "user_agency": "0003",
      "user_account": "11223344-5"
    }
  ]
}

Pagination Fields

Field	Type	Description
worked	Boolean	Always returns `true` when the request is successful
next	String	Complete URL to fetch the next page of transactions. `null` if this is the last page.
previous	String	Complete URL to fetch the previous page of transactions. `null` if this is the first page.
results	Array	Array of transaction records (see Transaction Fields below)

Transaction Fields

Field	Type	Description
credit_or_debit	String	Transaction direction: `CREDIT` (money entering the account) or `DEBIT` (money leaving the account)
transaction_type	String	Type of transaction. Possible values: `PIX_CASHIN`, `PIX_CASHOUT`, `PIX_CASHIN_TAX`, `PIX_CASHOUT_TAX`, `PIX_CASHOUT_TAX_MED`, `PIX_CHARGEBACK`, `PIX_CHARGEBACK_REFUND`, `PIX_CASHOUT_REFUND`, `PIX_CREDIT_IN_ACCOUNT`
amount	Float	Transaction amount in BRL (Brazilian Real). Always positive regardless of credit/debit direction.
date_time	DateTime	Transaction date and time in local timezone (Brazilian time, GMT-3). Format: ISO 8601.
date_time_utc	DateTime	Transaction date and time in UTC timezone. Format: ISO 8601. Use this for consistent time comparisons across timezones.
identification	String	Transaction identifier. For PIX transactions, this is the end-to-end ID. May be `null` for some transaction types.
code_transaction	String	Unique transaction code. Usually matches `identification`. May be `null` for some transaction types.
code	Integer	Internal database ID of the transaction record. Unique across all transactions.
qr_code_id	Integer	ID of the PIX QR Code used for this transaction (if applicable). `null` if the transaction did not use a QR Code.
transaction_id	Integer	ID of the associated transaction object (if applicable). `null` if not linked to a transaction object.
tag_id	String	Custom tag/label associated with the transaction. Useful for grouping or identifying transactions in your system. `null` if no tag was assigned.
end_to_end	String	PIX end-to-end identifier (UUID format). Unique identifier for PIX transactions. `null` for non-PIX transactions.
user_name	String	Name of the counterparty (person or company involved in the transaction). `null` if not available or not applicable.
user_document	String	CPF or CNPJ of the counterparty (formatted with dots and dashes, e.g., "123.456.789-00"). `null` if not available.
user_agency	String	Bank branch/agency number of the counterparty. `null` if not available or not applicable.
user_account	String	Account number of the counterparty (formatted with dash, e.g., "12345678-9"). `null` if not available or not applicable.

Transaction Direction (credit_or_debit):

Value	Description
`CREDIT`	Money entering the account
`DEBIT`	Money leaving the account

Transaction Types (transaction_type):

Value	Description
`PIX_CASHIN`	PIX incoming payment received
`PIX_CASHOUT`	PIX outgoing payment sent
`PIX_CASHIN_TAX`	Tax charged on PIX incoming payment
`PIX_CASHOUT_TAX`	Tax charged on PIX outgoing payment
`PIX_CASHOUT_TAX_MED`	Tax charged on PIX outgoing payment for MED
`PIX_CHARGEBACK`	PIX chargeback transaction
`PIX_CHARGEBACK_REFUND`	Refund of a PIX chargeback
`PIX_CASHOUT_REFUND`	Refund of a PIX outgoing payment
`PIX_CREDIT_IN_ACCOUNT`	PIX credit directly added to account

Error Responses

HTTP Code	Error Message	Description
400	Account not found	The account was not found or does not belong to your company.
400	Cursor does not belong to this account	The cursor was created for a different account. Ensure you're using the cursor with the same account parameters.
400	Cursor not found or expired	The cursor token is invalid, not found, or has expired. Start a new request from the first page.
400	direction (next or previous) is required when cursor is provided	You must specify `direction` parameter (`next` or `previous`) when using cursor-based pagination.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature.
403	Forbidden	Your user does not have the necessary permissions to access this account's statement.
404	Not found	The account does not exist.
422	Validation error	One or more query parameters are invalid. Check date formats (ISO 8601), limit range (1-100), and that `start` is before `end`.

Business Rules

Account Validation:

Account must exist in the system
Account must belong to your company
User must have permission to access this specific account's transactions
Both branch identifier and account number are required and must match exactly

Date Range Validation:

Both start and end parameters are required
start must be before end
Dates must be in ISO 8601 format with timezone (e.g., 2026-04-01T00:00:00Z)
Maximum period length: No hard limit, but very large ranges may impact performance
Recommended maximum: 90 days per request for optimal performance

Pagination Limits:

Minimum records per page: 1
Maximum records per page: 100
Default records per page: 50
Changing limit during pagination applies to the current cursor position

Transaction Ordering:

Transactions are ordered by creation date (newest to oldest by default)
Order is consistent throughout pagination
The same date range will always return transactions in the same order

Cursor Expiration:

Cursors are stored temporarily and expire after a period of inactivity
Typical expiration: 15-30 minutes from last use
If a cursor expires, start a new request from the first page
Cursors are tied to specific account and date range parameters

Pagination Usage

How Cursor-Based Pagination Works:

This API uses opaque cursor-based pagination. You don't need to understand or parse the cursor—simply follow the URLs provided in the response.

First Request:

Make an initial request without cursor or direction parameters
The response includes next URL for the next page (or null if no more pages)
The previous field is always null on the first page

Navigate Forward:

Use the complete URL from the next field in the response
The cursor and direction parameters are automatically included in the URL

Navigate Backward:

Use the complete URL from the previous field in the response
The cursor and direction parameters are automatically included in the URL

Best Practices:

Always use the complete URLs provided in next and previous fields
Check if URLs are null before making requests
If a cursor expires, start from the first page again
Don't manually construct or parse cursor values
Don't change start or end parameters while using a cursor (this resets to first page)
Changing limit parameter applies to the current cursor position