Transactions API icon

Transactions API

(0 reviews)
Retrieve data related to transactions and settlement to integrate in to you systems or build reporting dashboards.

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:

EndpointPurposeTypical Users
GET /v2/transactionsComprehensive transaction reporting across all sales channels (PayOnSite, PayOnline, PayWish).Point-of-Sale (POS) controllers, store managers, customer support, BI teams.
GET /v2/transactions/{id}/eventsFull audit timeline of individual lifecycle events (Authorization, Capture, Refund, Cancellation).Integration developers, fraud analysts, payment engineers.
GET /v2/acquiringInterbank clearing details, interchange, scheme fees, Market Pay margins, and invoice deductions.Financial controllers, billing accountants, revenue managers.
GET /v2/settlementBank 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

HeaderRequiredExample
client_idTRUEh515c5a6d534406cbad56c96cb747242
client_secretTRUE451bA70DCDA49676Ac9A9E12a9af94e7

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) - merchantId
  • account_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 grossAmount and netAmount.
  • Refunds: Negative grossAmount and netAmount (refundedTransactionId links 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:

APIField NameQuery ParameterRole
GET /v2/settlementsettlementBatchIdsettlement_batch_idMaster payout transfer identifier (e.g. 0nGm4bIQjYOec1RyRTc0EhA3_0I=).
GET /v2/acquiringsettlement.batchIdbatch_idForeign 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:

ConceptTransactions API (/v2/transactions)Events API (/v2/transactions/{id}/events)Role
Master KeyrootTransactionalEventIdPath parameter {transaction_id} & rootTransactionalEventIdUnifies all operations belonging to a single payment attempt or flow.
Initial OperationfirstTransactionalEventIdeventId (where eventType is Authorization or Purchase)Directly points to the first event record.
Latest OperationlastTransactionalEventIdeventId (where eventType is Capture, Refund, etc.)Directly points to the latest event record.
Event ChainingN/AparentEventIdLinks an event to its parent (e.g. Capture $\to$ Authorization).
Refund TrackingrefundedTransactionIdparentTranctionIdLinks 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:

FieldFormatRecommended Use Case
firstOperationDatetime / lastOperationDatetimeISO 8601 UTC (YYYY-MM-DDThh:mm:ssZ)Centralized data warehouse ETL, automated alerts, server-to-server syncs.
firstOperationDatetimeLocal / lastOperationDatetimeLocalLocal 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 CodeReasonMeaning & Recommended Action
200 OKSuccessRequest succeeded. Response body contains data.
400 Bad RequestValidation ErrorCheck query parameters (e.g. invalid date format, missing mandatory account_id).
401 UnauthorizedAuthentication FailureMissing or invalid client_id or client_secret headers.
403 ForbiddenAuthorization ErrorClient credentials do not have access to the requested account_id.
404 Not FoundResource MissingSpecific transaction ID or settlement batch ID not found.
500 Internal ErrorGateway ErrorTemporary 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 CodeMessage (errorMessage)Cause & ExplanationAction
10001Authorization declinedIssuing bank declined authorization.Check reason and rawResponseCode for the cardholder's bank refusal reason.
22014Card expiredThe payment card validity date has lapsed.Ask customer to provide an unexpired card.
22010Transaction reference not foundTarget transaction reference was not found for capture, void, or refund.Verify rootTransactionalEventId and ensure initial authorization succeeded.
10009Declined by 3rd party3-D Secure authentication failure or fraud engine block.Re-attempt 3DS challenge or request another card.
40010Authorization has been cancelledAttempted to capture a pre-authorization that was already cancelled.Initiate a new authorization.
10006Capture failedGateway capture transmission error with card clearing network.Re-attempt capture within validity window.
10002Void failedPre-auth cancellation failed (usually because capture is already confirmed).Execute a Refund instead of a void.
30003Routing not foundNo 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 CodeDescription (reason)MeaningCustomer Advice
116Not sufficient fundsCardholder account balance or credit line limit exceeded.Ask customer to fund account or use an alternate card.
117Incorrect PINCustomer entered an incorrect secret code.Retry PIN entry carefully.
106Allowable PIN tries exceeded3 consecutive wrong PIN entries; card chip temporarily blocked.Customer must unblock PIN at an ATM or via mobile banking app.
101Expired cardCard expiration date is in the past.Use renewed card.
119Transaction not permitted to cardholderCard account restrictions (e.g. online purchases disabled, international blocked).Customer should toggle permissions in their bank app.
121Exceeds withdrawal amount limitSpending velocity ceiling reached on card account.Contact issuing bank to raise limits.
190Switch to chip & PINContactless cumulative spending threshold reached.Insert card chip into terminal and enter PIN.
191SCA requiredStrong Customer Authentication required (PSD2).Complete biometric or SMS 3-D Secure challenge.
100 / 200Do not honorGeneral bank refusal without specific reason disclosed by issuer.Customer must contact their bank to authorize merchant.
907 / 909System malfunction / Switch inoperativeTemporary card network or issuer downtime.Wait a few moments and retry.
983No response from acquirerBank authorization host timed out.Retry transaction; verify terminal connection.

Reviews