API Docs
Version History
Field | Description | Sample |
05/08/25 | Version 1 - ClosedBatchReport: This version enables merchants to retrieve complete batch-level information by passing either the TPN alone, or in combination with batch date and/or batch number. | v1/batch-report |
The Batch Report API retrieves detailed batch reports for closed batches using the Terminal Profile Number (TPN), Batch Number, and Batch Date. The report includes the following:
Field | Description |
Batch Profiles | A list of all profiles included in this batch. Each profile includes terminal and processor configuration data and detailed transactions. |
Cash Payments | Total value and count of cash-based transactions. |
Alternative Payments | Total value and count of payments using alternate methods (e.g., ACH). |
Batch Total | Total value of all transactions in the batch, including tips and fees. |
Total Transactions | Count of all transactions included in the batch. |
Batch Number | Unique identifier automatically assigned to each batch. |
Total Tip | Cumulative tip amount collected across all transactions. |
Total Fee | Combined fee charged across all transactions. |
Total Without Fee | Total transaction amount before applying any fees. |
Prerequisites
For Sandbox (UAT)
Users should be onboarded on the iPOSpays sandbox (UAT) environment as a merchant and have a valid TPN.
For Production (Live)
Users should be onboarded on the iPOSpays production environment as a merchant and have a valid TPN.
If you do not have a TPN, contact your ISO or devsupport@dejavoo.io
Indicator | Description |
* | Mandatory |
** | Conditional |
How to Generate an Authentication Token
Follow the steps below to obtain your authentication token for accessing the Batch Report API:
Step 1: Access the Authentication Token API
Refer to the official documentation to understand the request structure and response handling:
iPOSpays Authentication Token API
Step 2: Prepare Your API Credentials
Before making a request, ensure you have the necessary credentials issued by iPOSpays. These include:
{
"apiKey": "your_api_key_here", // Required: Your assigned API key from iPOSpays
"secretKey": "your_secret_key_here", // Required: Your assigned secret key from iPOSpays
"scope": "BatchReport" // Required: Use "BatchReport" for retrieving closed batch reports
}- apiKey: Provided by iPOSpays. Contact devsupport@dejavoo.io or your Dejavoo representative if you haven’t received it.
- secretKey: Shared along with the API key.
- scope: Must be set to "BatchReport" for accessing Closed Batch data.
Step 3: Use the Token
After a successful API call, a valid authentication token will be returned in the response.
Include this token in the header of all subsequent Batch Report API requests to ensure authorized access.
Always ensure you’re using the correct token for the respective environment. Tokens generated in UAT will not work in production and vice versa.
Request Parameters - Header Objects
Field | Type | Description |
token * | String | Auth token generated from the portal (see above) |
Request Parameters - Body Objects
Field | Type | Description |
merchantId * | String | Terminal Profile Number (TPN) assigned to the merchant |
batchDate* * | String | Format: YYYY-MM-DD. Required if batchNo is used |
batchNo* * | String | Required if batchDate is used |
- Provide both
batchDateandbatchNoto fetch a specific batch. - To fetch multiple batches, use just batchDate or only merchantId.
Batch Report JSON Structure
This document outlines the fields present in the batch report JSON payload.
Field | Type | Description |
batch_profiles | Array of Objects | A list of profiles included in this batch, each containing detailed batch information. |
cash_payment | Object | Summary of cash payment transactions. |
alter_payments | Object | Summary of alternative payment types (e.g., ACH) |
batch_total | Number | Total amount of all transactions in the batch |
total_transactions | Number | Total number of transactions in the batch |
batch_number | String | Unique batch identifier |
batch_status | String | Status of the batch |
total_tip | Number | The total tip amount across all transactions in the batch. |
total_fee | Number | Total fee charged across all transactions in the batch. |
total_without_fee | Number | The total amount of transactions in the batch, excluding fees. |
batch_profiles Object Fields
Field | Type | Description |
profile_name | String | The name of the batch profile. |
profileCode | String | A code identifying the batch profile. |
processorData | Object | Contains detailed data related to the payment processor. |
batch_number | String | The batch number specific to this profile. |
transaction_no | Number | The number of transactions within this specific batch profile. |
settleDate | String | The settlement date and time for the batch profile in ISO 8601 format (e.g., "YYYY-MM-DDTHH:mm:ss.SSSZ"). |
batch_total | Number | The total monetary amount for this batch profile. |
batchBase | Number | The base amount for the batch. |
tip | Number | The total tip amount for this batch profile. |
discount | Number | The total discount amount for this batch profile. |
without_tip | Number | The total amount for this batch profile, excluding tips. |
without_tax | Number | The total amount for this batch profile, excluding taxes. |
customFieldFeeType | String | A placeholder or indicator for a custom fee type, currently null. |
fee | Number | The total fee amount for this batch profile. |
taxAmount | Number | The total tax amount for this batch profile. |
localTaxAmount | Number | The local tax amount for this batch profile. |
stateTaxAmount | Number | The state tax amount for this batch profile. |
withoutLocalTaxAmount | Number | The total amount for this batch profile, excluding local taxes. |
withoutStateTaxAmount | Number | The total amount for this batch profile, excluding state taxes. |
without_discount | Number | The total amount for this batch profile, excluding discounts. |
without_fee | Number | The total amount for this batch profile, excluding fees. |
batch_summary | Array of Objects | A summary of transaction types within this batch profile. |
batch_details | Array of Objects | Detailed information for each transaction within this batch profile. |
summary_type | String | Indicates the type of batch summary (e.g., "default"). |
detail_type | String | Indicates the type of batch details (e.g., "default"). |
batch_summary_group | Array | Placeholder for grouped batch summary data, currently empty. |
batch_details_group | Array | Placeholder for grouped batch details data, currently empty. |
processorData Object Fields
Field | Type | Description |
developerID | String | Identifier for the developer |
applicationID | String | Identifier for the application |
Mid | String | Merchant ID |
Agent | String | Agent code |
Chain | String | Chain code |
Store | String | Store number |
TermNo | String | Terminal number |
TermId | String | Terminal ID |
dba | String | "Doing Business As" name |
city | String | Merchant city |
state | String | Merchant state (two-letter code) |
address | String | Merchant address |
zipCode | String | Merchant zip code |
phone | String | Merchant phone number |
Bin | String | Bank Identification Number |
Mcc | String | Merchant Category Code |
DeviceCode | String | Code Identifying the device |
IndustryCode | String | Code Identifying the industry |
dsGroup | String | Data stream group identifier |
batch_summary Object Fields
Field | Type | Description |
inx | String | An index for the summary entry. |
type | String | The type of transaction summarized (e.g., "SALE"). |
profileId | String | The profile ID associated with this summary. |
transaction_no | Number | The count of transactions for this type in the summary. |
amount | Number | The total amount for this transaction type in the summary. |
txName | String | The name of the transaction type |
batch_details Object Fields
Field | Type | Description |
groupType | String | A placeholder for transaction group type |
transactionId | String | A unique identifier for the individual transaction |
profileId | String | The profile ID associated with this transaction. |
invoiceNumber | String | The invoice number for the transaction. |
tipAmount | Number | The tip amount for this specific transaction. |
totalTaxAmount | Number | The total tax amount for this specific transaction. |
localTaxAmount | Number | The local tax amount for this specific transaction. |
posRequestDate | String | The date of the POS request (YYYY-MM-DD). |
posRequestTime | String | The time of the POS request (HH:mm:ss). |
approvalCode | String | The approval code for the transaction. |
stateTaxAmount | Number | The state tax amount for this specific transaction. |
reducedTax | Number | The reduced tax amount, if applicable |
deferredAuth | String | Information regarding deferred authorization, if any. |
snfNumber | String | Service Number Field, if applicable |
commercialTaxAmount | Number | The commercial tax amount, if applicable. |
rrn | String | Retrieval Reference Number for the transaction. |
externalRefId | String | An external reference ID. |
appCode | String | Application code. |
feeAmount | Number | The fee amount for this specific transaction. |
voidFlag | String | Indicates if the transaction was voided ("N" for No, "Y" for Yes). |
baseAmount | Number | The base amount of the transaction. |
customFee | Number | A custom fee amount for the transaction. |
onlyTipAmt | Number | The tip amount, specifically for tip-only transactions or if applicable. |
surcharge | Number | The surcharge amount for the transaction. |
discount | Number | The discount amount for the transaction. |
serviceFee | Number | The service fee amount for the transaction. |
merchantFee | Number | The merchant fee amount for the transaction. |
reducedTaxFee | String | Reduced tax fee information. |
account | String | Masked account number (e.g., credit card number). |
type | String | The type of transaction (e.g., "SALE"). |
amount | Number | The total amount of the transaction. |
card | String | The type of card used (e.g., "VISA"). |
approvedAmount | Number | The approved amount for the transaction. |
adjustedTipAmount | Number | The adjusted tip amount, if any. |
tagValue | String | A placeholder for tag value |
tagLabel | String | A placeholder for tag label |
cash_payment Object Fields
Field | Type | Description |
data | Array | An array containing details of cash transactions. |
cash_txn_count | Number | The total count of cash transactions. |
cash_payment_total | Number | The total amount of cash payments. |
data ObjectData (Sane Object is used for cash_payment & alter_payment)
Field | Type | Description |
id | String | A unique identifier for this specific transaction. |
hostResponseCode | String | The response code received from the host system. |
posResponseCode | String | The response code from the Point of Sale (POS) system. |
txAmount | Number | The transaction amount. |
serviceFee | Number | The service fee applied to this transaction. |
DiscountFee | Number | The discount fee applied to this transaction. |
cashDiscount | Number | The cash discount amount. |
onlyTipAmt | Number | The tip amount for this transaction (if applicable, e.g., for tip-only adjustments). |
maskedPan | String | A masked version of the Primary Account Number (PAN), typically for a card. |
rrn | String | Retrieval Reference Number for the transaction. |
txName | String | The name of the transaction type. |
totalAmount | Number | The total amount of the transaction. |
approvalCode | String | The approval code for the transaction. |
txDate | String | The date and time the transaction occurred in ISO 8601 format (e.g., 'YYYY-MM-DDTHH:mm:ss.SSSZ'). |
txTime | String | The time portion of the transaction (HH:mm:ss). |
tpn | String | Transaction Processor Number or similar identifier. |
invoiceNumber | String | The invoice number associated with the transaction. |
createdAt | String | The date and time when this transaction record was created in ISO 8601 format. |
updatedAt | String | The date and time when this transaction record was last updated in ISO 8601 format. |
transactionId | String | A unique identifier for the transaction. |
commonMode | String | The common mode of the transaction (e.g., 'MOBILE'). |
sourceType | String | The source type of the payment (e.g., 'Paya ACH'). |
additionalDetails | String | Placeholder for additional details. |
destType | String | The destination type of the payment (e.g., 'Paya ACH'). |
transactionType | String | The type of transaction (e.g., 'CHECK'). |
alter_payments Object Fields
Field | Type | Description |
data | Array | An array containing details of cash transactions. |
alter_txn_count | Number | The total count of cash transactions. |
alter_payment_total | Number | The total amount of cash payments. |
total_tip | Number | The total tip amount for give settled. |
Base URL
Production:
Sandbox:
Endpoints
api/v1/batch-report
api/v1/batch-report
api/v1/batch-report