Inicio rápido: tu primer pago

Este inicio rápido te lleva desde un terminal conectado hasta un pago con tarjeta completado a través de la API en la nube. Tu TPV envía una solicitud REST a la plataforma Market Pay a través de internet, y la plataforma la retransmite al terminal.

URLs base:

• Producción — https://eci.market-pay.com
• Preproducción — https://eci-stg.market-pay.com

Herramienta de demostración: para permitirte probar nuestra implementación (acceso con registro)

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

1. Comprueba que el terminal está en línea

GET /terminals lista los terminales actualmente conectados para el código de tu tienda. Si tu terminal no está en la lista, no se puede alcanzar — consulta Solución de problemas antes de continuar.

2. Realiza un pago

POST /process-transaction/{terminal-id}. Los importes están en unidades menores (1000 = 10,00 €) y currency es un código numérico ISO 4217 (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. Obtén el resultado

Hay dos formas en que se recibe el resultado, controladas por el parámetro de consulta waitTime (segundos):

• Sincrónicamente — si la transacción termina dentro de waitTime, la llamada devuelve 201 con el TransactionResult.
• Asincrónicamente — si tarda más, la llamada devuelve 202 Accepted y el resultado se entrega a tu notificationUrl. Las actualizaciones de estado (WAITING_FOR_CARD, PIN_REQUIRED, BANK_AUTHORIZATION, COMPLETED) se envían allí durante todo el proceso. Consulta Notificaciones y el modelo asíncrono.

En el resultado, status: OK y responseCode: "000" significan que el pago fue aprobado. Guarda terminalTransactionId — lo necesitas para cancelar el pago o completar una preautorización.

Reglas que evitan fallos silenciosos

• El ID del terminal distingue mayúsculas y minúsculas — el prefijo del fabricante debe estar en MAYÚSCULAS (PAX:…, no pax:…), o la llamada devuelve 404.
• currency debe coincidir con la moneda configurada en el terminal — una discrepancia es rechazada con 404.
• ecrTransactionId tiene un máximo de 35 caracteres — valores más largos son rechazados.
• Los importes están en unidades menores — 1000 equivale a 10,00 €, no a 1000 €.