Report

General Information

Integrators who have chosen the Pix Hub integration path should be aware that this report API only returns transactions processed through PSP Fiserv. Transactions completed through any other PSP routed via Pix Hub will not appear in the report results.

GET /v2/apm/pix/report/transactions

Advanced PIX transaction query, allowing filtering by period, document, Pix key, txid, endToEnd, amounts, transaction types, merchant CNPJ, as well as pagination and multiple integrators. Returns a detailed list of transactions, the criteria used, pagination details, a summary of credits, debits, available balance, and additional messages.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token for authentication	yes	string (bearerToken)
pixKey	query	Pix key of the account	no	string
documentNumber	query	List of account documents (can be multiple)	no	array of strings
startDate	query	Filter transactions after this date and time	yes	DateTime (ISO 8601)
endDate	query	Filter transactions before this date and time	yes	DateTime (ISO 8601)
txid	query	Transactions unique identifier	no	string
endToEnd	query	Pix transaction unique end to end identifier	no	string
pagination.currentPage	query	Page number to be retrieved	yes	int
pagination.pageSize	query	Page size to be retrieved	yes	int
minAmount	query	Minimum transaction amount	no	decimal
maxAmount	query	Maximum transaction amount	no	decimal
transactionTypes	query	List of transaction types to filter (0-14)	no	array of int
merchantCnpj	query	Merchant CNPJ	no	string
accountIdToGetBalance	query	Account ID to query available balance	no	Guid
originChannel	query	Origin channel of the transaction. See Origin Channel	no	int

Response Fields

Field	Type	Description
result	array	List of transactions
result.txid	string	Transactions unique identifier
result.amount	decimal	Amount of the transaction (BRL). See Amount Fields
result.paidAmount	decimal	Amount actually paid (BRL). See Amount Fields
result.createdAt	DateTime (ISO 8601)	Transaction date and time
result.movementType	string	Type of movement: Debit, Credit
result.transactionType	string	Transaction Type. See the complete table in Transaction Types
result.endToEndId	string	Unique end to end id
result.accountCnpj	string	Account CNPJ
result.pixKey	string	Account Pix Key
result.thirdPartyName	string	Name of the third party (external) involved in the transaction
result.merchantCnpj	string	Merchant CNPJ
result.inconsistencyReproval	int	In case of reproval by the inconsistency prevention engine: 1 - Inconsistency (can be null)
result.agency	string	Destination account branch
result.accountNumber	string	Destination account number
result.accountType	string	Destination account type
result.bankName	string	Destination bank name
result.bankIspb	string	Destination bank ISPB
result.bankPixKey	string	Destination bank Pix Key
result.userEmail	string	User email
result.ispb	string	PSP ISPB
result.ispbName	string	PSP name
result.bankCompeCode	string	COMPE Code (Check and Other Document Clearing System)
result.originAgency	string	Origin branch
result.originAccountNumber	string	Origin account number
result.integratorTradeName	string	Trade name of the integrator that owns the account
result.integratorLegalName	string	Legal name of the integrator that owns the account
criteria	object	Search criteria used
criteria.startDate	string (ISO 8601)	Start date filter used
criteria.endDate	string (ISO 8601)	End date filter used
criteria.pixKey	string	Pix key filter used
criteria.documentNumber	array	Document filter used
criteria.txid	string	Txid filter used
criteria.endToEndId	string	End to end filter used
summary	object	Summary of values
summary.sumAmountCredits	decimal	Sum of all credits
summary.sumAmountDebits	decimal	Sum of all debits
summary.availableBalance	decimal	Available balance (optional, only returns if accountIdToGetBalance was provided)
summary.additionalMessage	string	Additional message (can be null)
summary.errorMessage	string	Error message (can be null)
pagination	object	Pagination information
pagination.currentPage	int	Current page retrieved
pagination.pageSize	int	Current page size
pagination.totalPages	int	Total pages to be retrieved
pagination.totalItems	int	Total items to be retrieved

Response Example

{
  "criteria": {
    "pixKey": "4d2dd55d-d1ab-492b-868e-6b1a2791dc0b",
    "documentNumber": [
      "14821268000107"
    ],
    "startDate": "2025-01-01",
    "endDate": "2029-12-31",
    "txid": "2a2cc743-3913-48ea-91fe-13256ab3c3d2",
    "endToEndId": "E144654798498498465123"
  },
  "result": [
    {
      "createdAt": "2025-06-06T04:57:20.882Z",
      "movementType": "1",
      "transactionType": "1",
      "amount": 99.99,
      "paidAmount": 99.99,
      "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "txid": "42474ba2-fd99-43b9-b688-52fb7a74106d",
      "accountCnpj": "14821268000107",
      "pixKey": "4d2dd55d-d1ab-492b-868e-6b1a2791dc0b",
      "thirdPartyName": "John Mary",
      "inconsistencyReproval": 1,
      "merchantCnpj": "13207930000162",
      "agency": "0001",
      "accountNumber": "123456",
      "accountType": "Conta Corrente",
      "bankName": "Banco Exemplo",
      "bankIspb": "00000000",
      "bankCompeCode": "341",
      "bankPixKey": "980be6da-75b4-42f6-a505-13ba01221c6f",
      "userEmail": "[email protected]",
      "ispb": "12345678",
      "ispbName": "PSP Fiserv",
      "originAgency": "0001",
      "originAccountNumber": "654321",
      "integratorTradeName": "Acme Solutions",
      "integratorLegalName": "Acme Solutions Ltda"
    }
  ],
  "summary": {
    "sumAmountCredits": 99.99,
    "sumAmountDebits": 0,
    "availableBalance": 0,
    "additionalMessage": null,
    "errorMessage": null
  },
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1
  }
}

GET /v1/apm/pix/report/settlements

PIX settlement query, allowing filtering by document, period, Pix key, authorization status, and pagination. Returns a detailed list of completed settlements, the criteria used, and pagination information.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
pixKey	query	Account's Pix Key	no	string
documentNumber	query	CNPJ number	no	string
startDate	query	Start date for consultation	yes	DateTime (ISO 8601)
endDate	query	End date for consultation	yes	DateTime (ISO 8601)
status	query	Settlement Status	no	integer
pagination.currentPage	query	Current Page	yes	integer
pagination.pageSize	query	Itens per page	yes	integer

Response Fields

Field	Type	Description
criteria	object	Search criteria used
criteria.pixKey	string	Pix key filtered
criteria.documentNumber	string	Client document filtered
criteria.startDate	string (ISO 8601)	Start date filter
criteria.endDate	string (ISO 8601)	End date filter
criteria.status	string	Status
results	array	List of settlements
results.totalAmount	decimal	Net settlement amount
results.totalGrossAmount	decimal	Gross settlement amount
results.totalFeeAmount	decimal	Fees amount
results.status	string (enum)	Settlement Status
results.pixKey	string	Account Pix Key
results.errorMessage	string	Error message (can be null). See Settlement Report Error Codes
results.createdAt	string (ISO 8601)	Settlement creation date and time
results.endToEnd	string	Transaction end to end
results.settlement	object	Settlement destination account data
results.settlement.pixKey	string	Settlement account Pix Key
results.settlement.bankAccount	object	Settlement account bank details
results.settlement.bankAccount.type	string	Account type code: `"CC"` - Checking Account, `"PG"` - Payment Account
results.settlement.bankAccount.bankCode	string	Bank ISPB code
results.settlement.bankAccount.agency	string	Account branch
results.settlement.bankAccount.accountNumber	string	Account number
results.settlement.bankAccount.cnpj	string	Account CNPJ
pagination	object	Pagination information
pagination.currentPage	int	Current page
pagination.pageSize	int	Items per page
pagination.totalPages	int	Total pages
pagination.totalItems	int	Total items

Response Example

{
  "criteria": {
    "pixKey": "ec961b3d-5ce3-4c5e-9a77-400f3fe13ab2",
    "documentNumber": "13207930000162",
    "startDate": "2024-10-01T15:25:30.812Z",
    "endDate": "2024-10-01T15:25:30.812Z",
    "status": 2
  },
  "results": [
    {
      "totalAmount": 99.00,
      "totalGrossAmount": 99.99,
      "totalFeeAmount": 0.99,
      "status": "Failed",
      "pixKey": "ec961b3d-5ce3-4c5e-9a77-400f3fe13ab2",
      "errorMessage": "02. Houve uma falha no pagamento",
      "createdAt": "2024-10-01T15:25:30.812Z",
      "endToEnd": "E01234567202410011525AB1CDEFGHI6",
      "settlement": {
        "pixKey": "ec961b3d-5ce3-4c5e-9a77-400f3fe13ab2",
        "bankAccount": {
          "type": "PG",
          "bankCode": "104",
          "agency": "0001",
          "accountNumber": "4321056789",
          "cnpj": "13207930000162"
        }
      }
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 0
  }
}

GET /v2/apm/pix/report/transactions/split/detailed

Query detailed report of transactions with split.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	yes	string
Authorization	header	Bearer Token used for authentication	yes	string (bearerToken)
startDate	query	Start date	yes	DateTime (ISO 8601)
endDate	query	End date	yes	DateTime (ISO 8601)
merchantCnpj	query	Merchant CNPJ	no	string
transactionTypes	query	Transaction types. See the complete table in Transaction Types	no	array[int]
pageNo	query	Page number	yes	int
pageSize	query	Items per page	yes	int

Response Fields

Field	Type	Description
result	array	List of transactions
result.date	DateTime (ISO 8601)	Transaction date and time
result.cnpj	string	Merchant CNPJ
result.txId	string	Transaction ID
result.endToEnd	string	Transaction End to End
result.txIdReverse	string	Reverse transaction ID (can be null)
result.transactionType	object	Transaction type. See Transaction Types for details
result.transactionType.id	int	Transaction type ID
result.transactionType.name	string	Transaction type name
result.transactionType.description	string	Transaction type description
result.amount	decimal	Transaction amount (BRL). See Amount Fields
result.paidAmount	decimal	Amount actually paid (BRL). See Amount Fields
result.targetCustomerFeeAmount	decimal	Target customer fee amount
result.appliedCustomerFeeAmount	decimal	Applied customer fee amount
result.appliedFiservFeeAmount	decimal	Applied Fiserv fee amount
result.appliedPartnerFeeAmount	decimal	Applied Partner fee amount
pagination	object	Pagination information
pagination.currentPage	int	Current page
pagination.pageSize	int	Page size
pagination.totalPages	int	Total pages
pagination.totalItems	int	Total items

Response Example

{
  "result": [
    {
      "date": "2025-06-06T04:57:20.882Z",
      "cnpj": "13207930000162",
      "txId": "42474ba2-fd99-43b9-b688-52fb7a74106d",
      "endToEnd": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "txIdReverse": null,
      "transactionType": {
        "id": 0,
        "name": "Payment",
        "description": "Cobrança"
      },
      "amount": 100.00,
      "paidAmount": 100.00,
      "targetCustomerFeeAmount": 1.00,
      "appliedCustomerFeeAmount": 1.00,
      "appliedFiservFeeAmount": 0.50,
      "appliedPartnerFeeAmount": 0.50
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

GET /v2/apm/pix/report/transactions/split/summary

Query summary report of transactions with split.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	yes	string
Authorization	header	Bearer Token used for authentication	yes	string (bearerToken)
startDate	query	Start date	yes	DateTime (ISO 8601)
endDate	query	End date	yes	DateTime (ISO 8601)
merchantCnpj	query	Merchant CNPJ	no	string
transactionTypes	query	Transaction types. See the complete table in Transaction Types	no	array[int]
pageNo	query	Page number	yes	int
pageSize	query	Items per page	yes	int

Response Fields

Field	Type	Description
result	array	List of summaries by transaction type
result.transactionType	object	Transaction type. See Transaction Types for details
result.transactionType.id	int	Transaction type ID
result.transactionType.name	string	Transaction type name
result.transactionType.description	string	Transaction type description
result.quantity	int	Number of transactions
result.amount	decimal	Sum of amounts (BRL). See Amount Fields
result.paidAmount	decimal	Sum of amounts actually paid (BRL). See Amount Fields
result.targetCustomerFeeAmount	decimal	Target customer fee amount
result.appliedCustomerFeeAmount	decimal	Applied customer fee amount
result.appliedFiservFeeAmount	decimal	Applied Fiserv fee amount
result.appliedPartnerFeeAmount	decimal	Applied Partner fee amount
pagination	object	Pagination information
pagination.currentPage	int	Current page
pagination.pageSize	int	Page size
pagination.totalPages	int	Total pages
pagination.totalItems	int	Total items

Response Example

{
  "result": [
    {
      "transactionType": {
        "id": 0,
        "name": "Payment",
        "description": "Cobrança"
      },
      "quantity": 10,
      "amount": 1000.00,
      "paidAmount": 1000.00,
      "targetCustomerFeeAmount": 10.00,
      "appliedCustomerFeeAmount": 10.00,
      "appliedFiservFeeAmount": 5.00,
      "appliedPartnerFeeAmount": 5.00
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

GET /v2/apm/pix/report/transactions/split/summary-by-cnpj

Query summary report of transactions with split, grouped by merchant CNPJ.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	yes	string
Authorization	header	Bearer Token used for authentication	yes	string (bearerToken)
startDate	query	Start date	yes	DateTime (ISO 8601)
endDate	query	End date	yes	DateTime (ISO 8601)
merchantCnpj	query	Merchant CNPJ	no	string
transactionTypes	query	Transaction types. See the complete table in Transaction Types	no	array[int]
pageNo	query	Page number	yes	int
pageSize	query	Items per page	yes	int

Response Fields

Field	Type	Description
result	array	List of summaries by merchant CNPJ and transaction type
result.cnpj	string	Merchant CNPJ
result.transactionType	object	Transaction type. See Transaction Types for details
result.transactionType.id	int	Transaction type ID
result.transactionType.name	string	Transaction type name
result.transactionType.description	string	Transaction type description
result.quantity	int	Number of transactions
result.amount	decimal	Sum of amounts (BRL). See Amount Fields
result.paidAmount	decimal	Sum of amounts actually paid (BRL). See Amount Fields
result.targetCustomerFeeAmount	decimal	Target customer fee amount
result.appliedCustomerFeeAmount	decimal	Applied customer fee amount
result.appliedFiservFeeAmount	decimal	Applied Fiserv fee amount
result.appliedPartnerFeeAmount	decimal	Applied Partner fee amount
pagination	object	Pagination information
pagination.currentPage	int	Current page
pagination.pageSize	int	Page size
pagination.totalPages	int	Total pages
pagination.totalItems	int	Total items

Response Example

{
  "result": [
    {
      "cnpj": "13207930000162",
      "transactionType": {
        "id": 0,
        "name": "Payment",
        "description": "Cobrança"
      },
      "quantity": 10,
      "amount": 1000.00,
      "paidAmount": 1000.00,
      "targetCustomerFeeAmount": 10.00,
      "appliedCustomerFeeAmount": 10.00,
      "appliedFiservFeeAmount": 5.00,
      "appliedPartnerFeeAmount": 5.00
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

Additional Information

Transaction Types

Reference table for transaction types used in report endpoints:

Code	Name	Description
0	Payment	Charge
1	Reverse	Reversal
2	Block	MED block
3	Unlock	MED unlock
4	SpecialReturn	Special Return Movement
5	Refund	Partial Refund
6	BacenJudTransfer	Bacen Jud Transfer
7	BacenJudBlock	Bacen Jud Block
8	BacenJudUnlock	Bacen Jud Unlock
9	ScheduledCashOut	Scheduled Cash Out
10	ImmediateCashOut	Immediate Cash Out
11	PixFee	Pix Fee
12	PixFeeReverse	Fee Reversal
13	SpecialReturnReverse	Special Return Reversal
14	ManagementAdjustment	Management Adjustments
15	CashInRejected	Cash-in rejected
16	CashOutRejected	Cash-out rejected
17	DueDatePayment	Due date payment
18	CashOutReverse	Cash Out Reversal

Amount Fields

Rules for the amount and paidAmount fields returned by the transaction report endpoints. In summary endpoints, the values are the sum of the transactions of each type.

Field	Transaction types	Returned value
amount	0 - Payment, 17 - DueDatePayment	Original charge amount
amount	Other types	Transaction amount
paidAmount	0 - Payment, 17 - DueDatePayment	Amount actually paid by the payer. In due date charges, it may differ from `amount` due to interest, penalty, discount or deduction
paidAmount	1 - Reverse, 13 - SpecialReturnReverse	Split endpoints: amount paid of the original charge. `/v2/apm/pix/report/transactions`: `0`
paidAmount	Other types	`0`

Settlement Error Codes

Error codes that are returned in the errorMessage field when a settlement fails.

Code	Name	Description
1	InvalidAccount	These are registration errors that require updates to the client's data. Examples: the root CNPJ of the domicile account does not match the CNPJ of the account at the PSP, or the account lacks settlement data.
2	ProcessingFailure	These are internal errors that can be retried. Typical causes include exceptions, timeouts, infrastructure failures, or HTTP call errors. This is the default error for such cases.
3	WithoutBalance	This can occur if, at the time of settlement execution, the sum of returns, refunds, and blocks consumes the total value of received charges, resulting in a zero balance to be settled. The record is created, but it is already assigned this error.
4	BlockedBalanceMED	The available balance is blocked due to fraud prevention triggers or suspicious activity detection. Settlement cannot proceed until the block is manually reviewed and released by the compliance team.
5	BlockedBalance	The available balance is blocked due to pending obligations, judicial holds, or internal compliance restrictions. It requires administrative action or resolution of the underlying issues before settlement can occur

Settlement Status

Code	Name	Description
0	Pending	Settlement awaiting processing — when the account settlement status is Pending.
1	Confirmed	Settlement completed successfully — when the account settlement status is Closed and has no errors.
2	Failed	Settlement failed — when the account settlement status is Failed, or when it is Closed but has an associated error.

Origin Channel

Reference table for origin channels used in report endpoints:

Code	Name	Description
1	ExternalIntegrator	External Integrator
2	ServicesModule	Services Module
3	ClientPortal	Client Portal
4	InternalAutomation	Internal Automation
5	MED	Special Return Mechanism (Mecanismo Especial Devolução)
6	BacenJud	Bacen Jud
7	BackOffice	BackOffice
8	SupportBackOfficePortal	Support BackOffice Portal

Updated 12 days ago

Did this page help you?