Transactions API
Market Pay Transactions/Reporting & Settlement APIs — Developer & Integration Guide
Welcome to the Market Pay Transactions/Reporting & Settlement API documentation. This suite provides automated programmatic access to your transaction lifecycles, card clearing fee calculations, and daily financial wire payouts.
1. Overview & Architecture
The Market Pay API suite is designed around four primary endpoints serving distinct operational and financial reconciliation needs:
| Endpoint | Purpose | Typical Users |
|---|---|---|
GET /v2/transactions | Comprehensive transaction reporting across all sales channels (PayOnSite, PayOnline, PayWish). | Point-of-Sale (POS) controllers, store managers, customer support, BI teams. |
GET /v2/transactions/{id}/events | Full audit timeline of individual lifecycle events (Authorization, Capture, Refund, Cancellation). | Integration developers, fraud analysts, payment engineers. |
GET /v2/acquiring | Interbank clearing details, interchange, scheme fees, Market Pay margins, and invoice deductions. | Financial controllers, billing accountants, revenue managers. |
GET /v2/settlement | Bank wire payouts, transfer statement labels, debtor/creditor balances, and fee deductions. | Treasury teams, financial accountants, cash management. |
Base URL:
PRODUCTION: https://api.market-pay.com/data/api
STAGING: https://api-rec.market-pay.com/data/api
2. Authentication & Security
This API is secured with JWT (JSON Web Token) authentication to ensure that all interactions are secure and authorized. Each API request must include a valid JWT token in the Authorization header, which verifies the identity and permissions of the requester. This ensures that sensitive information and operations are protected against unauthorized access.
A valid JWT token can be obtained by calling the below endpoints with required headers:
PRODUCTION: https://api.market-pay.com/auth/api/token
STAGING: https://api-rec.market-pay.com/auth/api/token
| Header | Required | Example |
|---|---|---|
| client_id | TRUE | h515c5a6d534406cbad56c96cb747242 |
| client_secret | TRUE | 451bA70DCDA49676Ac9A9E12a9af94e7 |
Your account responsible from MarketPay will provide you client_id and client_secret for Production and Staging.
3. Merchant Hierarchy & Scoping
Market Pay structures reporting using a standardized three-level hierarchy:
Account (e.g. Retail Group) - accountId
└── Company (e.g. Retail Enterprises SAS) - companyId
└── Store / Point of Sale (e.g. Retail Store Paris, POS 04) - merchantIdaccount_id(Mandatory): Scopes all queries to your top-level partner or corporate account.company_id(Optional): Filters data to a specific subsidiary or legal entity.merchant_id(Optional): Isolates a specific retail outlet, warehouse, or digital storefront.
4. Financial Reconciliation & Calculation Logic
Payout Calculation Formula
In the Settlement API (/v2/settlement), daily wire transfers are calculated as:
settledAmount = purchaseAmount - refundAmount - chargebackAmount + chargebackReversedAmount - totalAcquiringFees - chargedFees
Sign Conventions
- Purchases: Positive
grossAmountandnetAmount. - Refunds: Negative
grossAmountandnetAmount(refundedTransactionIdlinks to original purchase). - Chargebacks: Positive dispute amount deducted from turnover.
- Acquiring Fees: Deducted from turnover (
interchange+schemeFees+marketpayFees).
Invoiced Fee Collection Mechanism
Commercial service bills (such as POS terminal rental, equipment maintenance, monthly software subscriptions, or statutory taxes like Italian Imposta di bollo) can be collected directly from the merchant's card turnover:
- In /v2/acquiring, these items appear as clearing entries with transactionTypeV2: "Invoice Deduction" (or "Tax Deduction"), transactionType: "CREDIT", with the Invoice ID in authorisationCode and the Invoice Reference in orderNumber.
- In /v2/settlement, these items are summed under chargedFees (and total_collected_fees), deducting directly from settledAmount.
- Balance Rollovers: If daily turnover is insufficient to cover deductions, the uncollected remainder rolls over to the next payout batch via balance and balanceTransferAmount.
Cross-API Linking via the Settlement ID
The Settlement API and Advanced Acquiring API are connected via a shared 28-character identifier, the Settlement ID:
| API | Field Name | Query Parameter | Role |
|---|---|---|---|
GET /v2/settlement | settlementBatchId | settlement_batch_id | Master payout transfer identifier (e.g. 0nGm4bIQjYOec1RyRTc0EhA3_0I=). |
GET /v2/acquiring | settlement.batchId | batch_id | Foreign key linking individual clearing transactions to the payout batch. |
Reconciliation Integrity:
- $\sum \text{grossAmount}{\text{acquiring}} = \text{grossAmount}{\text{settlement}}$
- $\sum \text{totalAcquiringFees}{\text{acquiring}} = \text{totalAcquiringFees}{\text{settlement}}$
- $\sum \text{netAmount}{\text{acquiring}} - \text{chargedFees} = \text{settledAmount}{\text{settlement}}$
Cross-API Linking between Transactions and Events
The Transactions API (/v2/transactions) and Events API (/v2/transactions/{id}/events) are linked by Market Pay's master transaction key:
| Concept | Transactions API (/v2/transactions) | Events API (/v2/transactions/{id}/events) | Role |
|---|---|---|---|
| Master Key | rootTransactionalEventId | Path parameter {transaction_id} & rootTransactionalEventId | Unifies all operations belonging to a single payment attempt or flow. |
| Initial Operation | firstTransactionalEventId | eventId (where eventType is Authorization or Purchase) | Directly points to the first event record. |
| Latest Operation | lastTransactionalEventId | eventId (where eventType is Capture, Refund, etc.) | Directly points to the latest event record. |
| Event Chaining | N/A | parentEventId | Links an event to its parent (e.g. Capture $\to$ Authorization). |
| Refund Tracking | refundedTransactionId | parentTranctionId | Links a refund event to the original purchase's rootTransactionalEventId. |
5. Timestamps: UTC vs. Local Store Time
To accommodate both centralized reporting and individual point-of-sale cash balancing, dual timestamp fields are provided:
| Field | Format | Recommended Use Case |
|---|---|---|
firstOperationDatetime / lastOperationDatetime | ISO 8601 UTC (YYYY-MM-DDThh:mm:ssZ) | Centralized data warehouse ETL, automated alerts, server-to-server syncs. |
firstOperationDatetimeLocal / lastOperationDatetimeLocal | Local store ISO (YYYY-MM-DDThh:mm:ss) | Physical store closing, cashier shifts, POS reconciliation (ticket de caisse). |
6. Common Developer & Reconciliation Workflows
Workflow 1: Fetching Yesterday's In-Store Transactions
curl -X GET "https://api.market-pay.com/v2/transactions?\
account_id=ACT-FR-00123&\
first_payment_date_min=2026-10-22T00:00:00Z&\
first_payment_date_max=2026-10-22T23:59:59Z&\
payment_solution=PayOnSite&\
limit=50" \
-H "client_id: $CLIENT_ID" \
-H "client_secret: $CLIENT_SECRET" \
-H "Accept: application/json"Workflow 2: Reconciling a Bank Wire Transfer & Drilling Down into Transactions
Step 1 — Retrieve the settlement payout for your bank statement date:bash
curl -X GET "https://api.market-pay.com/v2/settlement?\
account_id=ACT-FR-00123&\
settlement_date_min=2026-10-23&\
settlement_date_max=2026-10-23" \
-H "client_id: $CLIENT_ID" \
-H "client_secret: $CLIENT_SECRET" \
-H "Accept: application/json"
Step 2 — Drill down into the itemized transactions behind that payout using settlementBatchId:bash
curl -X GET "https://api.market-pay.com/v2/acquiring?\
account_id=ACT-FR-00123&\
batch_id=0nGm4bIQjYOec1RyRTc0EhA3_0I=&\
limit=100" \
-H "client_id: $CLIENT_ID" \
-H "client_secret: $CLIENT_SECRET" \
-H "Accept: application/json"
Workflow 3: Auditing Invoiced Service Deductions
Retrieve all non-transactional service bills deducted from your card processing stream:bash
curl -X GET "https://api.market-pay.com/v2/acquiring?\
account_id=ACT-FR-00123&\
transaction_type_v2=Invoice%20Deduction&\
operation_date_min=2026-10-01T00:00:00Z&\
operation_date_max=2026-10-31T23:59:59Z" \
-H "client_id: $CLIENT_ID" \
-H "client_secret: $CLIENT_SECRET" \
-H "Accept: application/json"
Workflow 4: Diagnosing a Payment Failure via the Event Timeline
When a transaction shows generalStatus: "Failed", inspect its sequential event log to find the exact issuer response code:bash
curl -X GET "https://api.market-pay.com/v2/transactions/DEC-91KM2DX10P99/events" \
-H "client_id: $CLIENT_ID" \
-H "client_secret: $CLIENT_SECRET" \
-H "Accept: application/json"
The response returns the full event trail, including errorMessage, reason (e.g., 51 - Insufficient funds), and gateway diagnostic payload in rawData.
7. Python Quickstart Script
import os
import requests
API_BASE = "https://api.market-pay.com"
HEADERS = {
"client_id": os.getenv("MP_CLIENT_ID"),
"client_secret": os.getenv("MP_CLIENT_SECRET"),
"Accept": "application/json"
}
def reconcile_daily_payout(account_id: str, settlement_date: str):
"""Retrieve settlement payout and drill down into constituent acquiring transactions."""
# 1. Fetch settlement batch payout
settlement_url = f"{API_BASE}/v2/settlement"
params = {
"account_id": account_id,
"settlement_date_min": settlement_date,
"settlement_date_max": settlement_date
}
res = requests.get(settlement_url, headers=HEADERS, params=params)
res.raise_for_status()
settlement_data = res.json()
for batch in settlement_data.get("output", []):
batch_id = batch["settlementBatchId"]
print(f"Settlement Batch: {batch_id}")
print(f" Bank Label: {batch['transferLabel']} | Wired Amount: {batch['settledAmount']} EUR")
print(f" Gross Sales: {batch['purchaseAmount']} EUR | Fees: {batch['totalAcquiringFees']} EUR | Invoices: {batch.get('chargedFees', 0)} EUR")
# 2. Drill down into itemized acquired transactions for this batch
acquiring_url = f"{API_BASE}/v2/acquiring"
acq_params = {"account_id": account_id, "batch_id": batch_id, "limit": 100}
acq_res = requests.get(acquiring_url, headers=HEADERS, params=acq_params)
acq_res.raise_for_status()
acq_data = acq_res.json()
print(f" -> Breakdown: {acq_data.get('total_transaction')} items in this payout transfer:")
for item in acq_data.get("output", []):
info = item["transactionInfo"]
print(f" - Type: {info['transactionTypeV2']:<18} | Gross: {info['grossAmount']:>7.2f} EUR | Order: {info.get('orderNumber') or 'N/A'}")
if __name__ == "__main__":
reconcile_daily_payout("ACT-FR-00123", "2026-10-23")8. HTTP Status Codes & Error Handling
8.1 HTTP Status Codes
| Status Code | Reason | Meaning & Recommended Action |
|---|---|---|
200 OK | Success | Request succeeded. Response body contains data. |
400 Bad Request | Validation Error | Check query parameters (e.g. invalid date format, missing mandatory account_id). |
401 Unauthorized | Authentication Failure | Missing or invalid client_id or client_secret headers. |
403 Forbidden | Authorization Error | Client credentials do not have access to the requested account_id. |
404 Not Found | Resource Missing | Specific transaction ID or settlement batch ID not found. |
500 Internal Error | Gateway Error | Temporary backend error. Implement exponential backoff retry (e.g. after 2s, 5s, 10s). |
8.2 Common Gateway Error Messages (errorMessage)
When an event shows eventStatus: "Error" or "Declined", inspect the gateway-level error message:
| Gateway Code | Message (errorMessage) | Cause & Explanation | Action |
|---|---|---|---|
10001 | Authorization declined | Issuing bank declined authorization. | Check reason and rawResponseCode for the cardholder's bank refusal reason. |
22014 | Card expired | The payment card validity date has lapsed. | Ask customer to provide an unexpired card. |
22010 | Transaction reference not found | Target transaction reference was not found for capture, void, or refund. | Verify rootTransactionalEventId and ensure initial authorization succeeded. |
10009 | Declined by 3rd party | 3-D Secure authentication failure or fraud engine block. | Re-attempt 3DS challenge or request another card. |
40010 | Authorization has been cancelled | Attempted to capture a pre-authorization that was already cancelled. | Initiate a new authorization. |
10006 | Capture failed | Gateway capture transmission error with card clearing network. | Re-attempt capture within validity window. |
10002 | Void failed | Pre-auth cancellation failed (usually because capture is already confirmed). | Execute a Refund instead of a void. |
30003 | Routing not found | No active acquiring contract or terminal profile configured for this scheme. | Verify terminal MID setup with Market Pay support. |
8.3 Common Bank Issuer Decline Codes (rawResponseCode & reason)
Card issuing banks return standardized 3-digit ISO 8583 response codes surfaced in rawData.rawResponseCode and explained in reason:
| ISO Code | Description (reason) | Meaning | Customer Advice |
|---|---|---|---|
116 | Not sufficient funds | Cardholder account balance or credit line limit exceeded. | Ask customer to fund account or use an alternate card. |
117 | Incorrect PIN | Customer entered an incorrect secret code. | Retry PIN entry carefully. |
106 | Allowable PIN tries exceeded | 3 consecutive wrong PIN entries; card chip temporarily blocked. | Customer must unblock PIN at an ATM or via mobile banking app. |
101 | Expired card | Card expiration date is in the past. | Use renewed card. |
119 | Transaction not permitted to cardholder | Card account restrictions (e.g. online purchases disabled, international blocked). | Customer should toggle permissions in their bank app. |
121 | Exceeds withdrawal amount limit | Spending velocity ceiling reached on card account. | Contact issuing bank to raise limits. |
190 | Switch to chip & PIN | Contactless cumulative spending threshold reached. | Insert card chip into terminal and enter PIN. |
191 | SCA required | Strong Customer Authentication required (PSD2). | Complete biometric or SMS 3-D Secure challenge. |
100 / 200 | Do not honor | General bank refusal without specific reason disclosed by issuer. | Customer must contact their bank to authorize merchant. |
907 / 909 | System malfunction / Switch inoperative | Temporary card network or issuer downtime. | Wait a few moments and retry. |
983 | No response from acquirer | Bank authorization host timed out. | Retry transaction; verify terminal connection. |