Quickstart: uw eerste betaling

Deze quickstart leidt u van een verbonden terminal naar een voltooide kaartbetaling via de Cloud API. Uw POS stuurt een REST-verzoek naar het Market Pay-platform via internet, en het platform geeft dit door aan de terminal.

Basis-URL's:

• Productie — https://eci.market-pay.com
• Pre-productie — https://eci-stg.market-pay.com

Demotool: om u in staat te stellen onze implementatie te testen (login toegang)

https://cloud-api-pos-demo.onrender.com/

1. Controleer of de terminal online is

GET /terminals toont de terminals die momenteel verbonden zijn met uw winkelcode. Als uw terminal niet in de lijst staat, is deze niet bereikbaar — zie Probleemoplossing voordat u verder gaat.

2. Neem een betaling aan

POST /process-transaction/{terminal-id}. Bedragen zijn in minimale eenheden (1000 = €10,00) en valuta is een ISO 4217 numerieke 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. Ontvang het resultaat

Er zijn twee manieren waarop het resultaat terugkomt, geregeld door de waitTime queryparameter (seconden):

• Synchronisch — als de transactie binnen waitTime voltooid is, retourneert de oproep 201 met het TransactionResult.
• Asynchronisch — als het langer duurt, retourneert de oproep 202 Accepted en wordt het resultaat geleverd aan uw notificationUrl. Statusupdates (WAITING_FOR_CARD, PIN_REQUIRED, BANK_AUTHORIZATION, COMPLETED) worden daar gedurende het proces naar toe gestuurd. Zie Meldingen en het asynchrone model.

status: OK en responseCode: "000" dat de betaling is goedgekeurd. Bewaar terminalTransactionId — u heeft dit nodig om de betaling te annuleren of een pre-autorisatie te voltooien.

Regels die stille fouten voorkomen

• Terminal-ID is hoofdlettergevoelig — het fabrikantvoorvoegsel moet in HOOFDLETTERS zijn (PAX:…, niet pax:…), anders retourneert de oproep 404.
• currency moet overeenkomen met de geconfigureerde valuta van de terminal — een mismatch wordt geweigerd met 404.
• ecrTransactionId mag maximaal 35 tekens lang zijn — langere waarden worden afgewezen.
• Bedragen zijn in minimale eenheden — 1000 is €10,00, niet €1000.