The Balance & Movements API allows merchants configured under the balance-based settlement model to query:
- Opening balance
- Closing balance
- Balance-impacting transactions within a specific date range
- Detailed operational transaction information
This enables merchants to:
- Monitor available funds
- Perform financial reconciliation
- Track collections, refunds, settlements, and fees
- Support financial decision-making based on current balances
📤POST Endpoint
Endpoint: {{base_url}}//merchant/balance/report
Please consult our Integrations team to obtain the environment-specific base URL required to begin your testing.
📝Creation Request
🔐Header
All requests to the this endpoint must include a custom Authorization header to ensure secure communication and proper merchant validation.
| Header | Required | Value Format |
|---|---|---|
| X-Api-Key | ✅ Yes | Public merchant identifier |
| X-Timestamp | ✅ Yes | Unix timestamp of the request. Validated against a time window ≤ 2 minutes. |
| X-Signature | ✅ Yes | HMAC_SHA512(secret-key, timestamp + api-key) |
The signature value must be a SHA-512 hash generated by concatenating the fields as decribed.
The secret-key is a credential provided by Monnet that must be used to build the final string before generating the hash.
📦Request Data
Specifies the structure and required parameters that must be included in the request body to successfully retrieve balance information and transaction movements, ensuring accurate reporting of opening balance, closing balance, and all balance-impacting transactions within the specified period.
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| reportType | string | Yes | Defines the type of report to be generated. Allowed values: EOD (End of Day) or Intraday. |
| startDateTime | datetime (ISO 8601) | Yes | Start date and time used as the reference point for the balance and transaction query. |
| endDateTime | datetime (ISO 8601) | Conditional | End date and time of the query range. Required when reportType is intraday; ignored for EOD. |
| currency | string | Yes | Currency in which the balance and transactions will be retrieved (ISO 4217 format, e.g., PEN, USD). |
| GMT | string | No | Time zone offset applied to the request. Default value is -5 if not provided. |
| pageNumber | integer | No | Page number to retrieve for paginated results. Minimum value is 1. Default is 1. |
| pageSize | integer | No | Number of records returned per page. Default is 50; maximum allowed value may apply. |
Example Request
{
"reportType": "Intraday",
"startDateTime": "2025-02-21T14:22:05Z",
"endDateTime": "2025-02-21T15:22:05Z",
"currency": "USD",
"GMT": "-5",
"pageNumber": 1,
"pageSize": 50
}
Success Response
| Field | Type | Description |
|---|---|---|
| initialBalance | Decimal | Opening balance prior to the first movement within the requested period |
| finalBalance | Decimal | Closing balance after the last movement within the requested period |
| pendingCredits | Decimal | Amount corresponding to authorized payin operations that have not yet been recognized in the available balance at the end of the query range. |
| pendingDebits | Decimal | Amount corresponding to liquidation requests generated but whose payment has not yet been executed at the end of the query range. |
| currency | String (ISO-4217) | Currency of the balance report |
| startDateTime | ISO-8601 Datetime | Start timestamp applied to the query |
| endDateTime | ISO-8601 Datetime | End timestamp applied to the query |
| pageNumber | Integer | Current page number returned |
| pageSize | Integer | Number of records per page |
| balanceDetails | Array | List of balance-impacting transactions |
| balanceDetails.recordDatetime | ISO-8601 Datetime | Timestamp when the movement was recorded in the balance ledger |
| balanceDetails.recordType | String | Movement type (Income / Outcome) |
| balanceDetails.concept | String | Business concept (Collection, Refund, Settlement, Fee, Tax, etc.) |
| balanceDetails.amount | Decimal | Transaction amount impacting the balance |
| balanceDetails.accumulatedBalance | Decimal | Running balance after applying the movement |
| balanceDetails.completedTime | ISO-8601 Datetime | Operational completion timestamp (authorization, settlement, refund, etc.) |
| balanceDetails.operationId | String (UUID) | Unique identifier of the transaction |
| balanceDetails.payinMethod | String | Payment method used (only for collections) |
| balanceDetails.virtualAccount | Object / Null | Virtual account information when the transaction originates from a virtual account |
| balanceDetails.virtualAccount.account.id | String | Virtual account identifier |
| balanceDetails.virtualAccount.account.accountType | String | Account type (e.g., CCI, Checking, Savings) |
| balanceDetails.virtualAccount.account.accountNumber | String | Virtual account number |
| balanceDetails.virtualAccount.owner.fullName | String | Account owner name |
| balanceDetails.virtualAccount.owner.documentType | String | Owner document type |
| balanceDetails.virtualAccount.owner.documentNumber | String | Owner document number |
| balanceDetails.virtualAccount.owner.referenceId | String | Merchant internal customer reference |
| balanceDetails.virtualAccount.payer.fullName | String | Depositor/payer name |
| balanceDetails.virtualAccount.payer.documentType | String | Depositor document type |
| balanceDetails.virtualAccount.payer.documentNumber | String | Depositor document number |
Example Response — Payin Transaction Details
{
"initialBalance": 15000.0,
"finalBalance": 18250.5,
"pendingCredits": 1200.0,
"pendingDebits": 500.0,
"currency": "PEN",
"startDateTime": "2025-02-01T00:00:00Z",
"endDateTime": "2025-02-01T23:59:59Z",
"pageNumber": 1,
"pageSize": 50,
"balanceDetails": [
{
"recordDatetime": "2025-02-01T10:15:30Z",
"recordType": "Credit",
"concept": "Collection",
"amount": 3250.5,
"accumulatedBalance": 18250.5,
"completedTime": "2025-02-01T10:16:05Z",
"operationId": "b7a91c44-7f8c-4c59-9c9b-21d7a7a3c123",
"payinMethod": "BANKTRANSFER",
"virtualAccount": null
}
]
}
Example Response — Virtual Account Transaction Details
{
"initialBalance": 15000.0,
"finalBalance": 21500.5,
"pendingCredits": 1200.0,
"pendingDebits": 500.0,
"currency": "PEN",
"startDateTime": "2025-02-01T00:00:00Z",
"endDateTime": "2025-02-01T23:59:59Z",
"pageNumber": 1,
"pageSize": 50,
"balanceDetails": [
{
"recordDatetime": "2025-02-01T10:15:30Z",
"recordType": "Credit",
"concept": "Collection",
"amount": 3250.5,
"accumulatedBalance": 18250.5,
"completedTime": "2025-02-01T10:16:05Z",
"operationId": "b7a91c44-7f8c-4c59-9c9b-21d7a7a3c123",
"payinMethod": "VIRTUAL_ACCOUNT",
"virtualAccount": {
"account": {
"id": "3f8c2a4e-9b6d-4f1e-b8a2-7d5c9e13a6f2",
"accountType": "CCI",
"accountNumber": "00212345678912345678"
},
"owner": {
"fullName": "Comercial ABC SAC",
"documentType": "RUC",
"documentNumber": "20123456789",
"referenceId": "CLI-45879"
},
"payer": {
"fullName": "Juan Perez",
"documentType": "DNI",
"documentNumber": "45879632"
}
}
},
{
"recordDatetime": "2025-02-01T14:32:18Z",
"recordType": "Credit",
"concept": "Collection",
"amount": 3250.0,
"accumulatedBalance": 21500.5,
"completedTime": "2025-02-01T14:33:02Z",
"operationId": "a9c2f77d-88b1-4e2f-9cdd-2e9f5a6b4d90",
"payinMethod": "VIRTUAL_ACCOUNT",
"virtualAccount": {
"account": {
"id": "7d2a1f4c-3e9b-4a7c-b5f2-1c6e8d9a0b11",
"accountType": "CCI",
"accountNumber": "00298765432198765432"
},
"owner": {
"fullName": "Comercial ABC SAC",
"documentType": "RUC",
"documentNumber": "20123456789",
"referenceId": "CLI-78901"
},
"payer": {
"fullName": "Maria Lopez",
"documentType": "DNI",
"documentNumber": "78451236"
}
}
}
]
}