Quickstart: your first payment

This quickstart takes you from a connected terminal to a completed card payment over the Cloud API. Your POS sends a REST request to the Market Pay platform over the internet, and the platform relays it to the terminal.

Note

Prerequisites: your mTLS client certificate is installed (see Authentication: mTLS certificates), the terminal is connected to the cloud, and you know its terminal ID in the form MANUFACTURER:SERIAL (for example PAX:1760019815).

Base URLs:

Production — https://eci.market-pay.com
Pre-production — https://eci-stg.market-pay.com

1. Check the terminal is online

GET /terminals lists the terminals currently connected for your store code. If your terminal is not in the list, it cannot be reached — see Troubleshooting before going further.

2. Take a payment

POST /process-transaction/{terminal-id}. Amounts are in minor units (1000 = €10.00) and currency is an ISO 4217 numeric code (978 = EUR):

POST https://eci.market-pay.com/process-transaction/PAX:1760019815?waitTime=20

{
  "transactionType": "PURCHASE",
  "amount": 1000,
  "currency": 978,
  "ecrTransactionId": "ticket-0001",
  "ecrParams": {
    "ecrId": "POS-01",
    "notificationUrl": "https://mypos.example.com/notifications",
    "printerAvailable": true,
    "operatorLanguage": "EN"
  }
}

3. Get the result

There are two ways the result comes back, controlled by the waitTime query parameter (seconds):

Synchronously — if the transaction finishes within waitTime, the call returns 201 with the TransactionResult.
Asynchronously — if it takes longer, the call returns 202 Accepted and the result is delivered to your notificationUrl. Status updates (WAITING_FOR_CARD, PIN_REQUIRED, BANK_AUTHORIZATION, COMPLETED) are pushed there throughout. See Notifications and the async model.

On the result, status: OK and responseCode: "000" mean the payment was approved. Persist terminalTransactionId — you need it to cancel the payment or complete a pre-authorization.

Rules that prevent silent failures

Terminal ID is case-sensitive — the manufacturer prefix must be UPPERCASE (PAX:…, not pax:…), or the call returns 404.
currency must match the terminal's configured currency — a mismatch is declined with 404.
ecrTransactionId is 35 characters maximum — longer values are rejected.
Amounts are in minor units — 1000 is €10.00, not €1000.