Providers
Metropol Kart

Metropol Kart

Metropol Kart is one of the providers in Lunixi Meal Cards. See Meal Card for the shared provider-selection, API and form contract. This page covers the QR, refund and reporting rules specific to the Metropol connection.

Metropol Kart uses MEAL_CARD payments with a QR code or a short code. The buyer approves the payment in the Metropol app. Creating a QR code does not confirm payment; the platform verifies the financial result with the provider.

QR display and NFC card UID reading on a physical POS use the separate physical POS meal-card contract. Android terminal app 0.1.4 handles these commands and starts payments from its PIN cashier form using server-offered provider/QR/NFC choices; physical-device and Metropol sandbox acceptance still require verification. Do not add an NFC UID to the web/form requests on this page.

The Metropol connection is available for the test environment. Live QR/web authorization and the live endpoint must be confirmed before live payments can be enabled. Read the methods and providers available to your account from GET /payments/methods.

Prepare the connection

Create a test Meal Cards → Metropol Kart connection in the panel. Enter the credentials and terminal identifiers issued by Metropol and enable QR/short-code payment. For Checkout Form, also enable the Meal Card method and the Metropol connection in Form Settings.

Connection fields: Consumer ID, Consumer Name, Reference No, Access Key, AES Key, Merchant Code and Terminal Code. Store these only in the provider connection in the panel; never send them in a payment body or to the browser.

This version covers Metropol Resto, TRY and a single charge. Do not send a card number, CVV, 2D/3D flags, installments or preauthorization. Same-batch cancellation through the refund flow, full/partial refunds and daily transaction reconciliation are also supported in TEST, subject to the connection’s operation permissions.

Accept a payment through the API

Call POST /payments/direct/payment from your merchant server using the existing Bearer and request-signing contract. Idempotency-Key is required; reuse the same key for retries of the same payment request. Never place your merchant Bearer token in the browser.

{
  "paymentMethod": "MEAL_CARD",
  "amount": "10000",
  "currency": "TRY",
  "orderId": "ORDER-METROPOL-001",
  "mealCard": { "providerCode": "METROPOL" }
}

amount is a minor-unit digit string: "10000" means TRY 100.00. To select a specific connection, send its optionId from the methods response at the top level. Additional mealCard fields must match the provider's inputFields; Metropol QR requires no buyer input fields.

The response includes an open customer action in data:

{
  "paymentId": "<payment-id>",
  "orderId": "ORDER-METROPOL-001",
  "status": "PROCESSING",
  "paymentMethod": "MEAL_CARD",
  "providerCode": "METROPOL",
  "action": {
    "id": "<action-id>",
    "type": "DISPLAY",
    "expiresAt": "2026-11-05T12:01:15.000Z",
    "display": {
      "qrCode": "<provider-qr-payload>",
      "shortCode": "012345"
    }
  }
}

These are placeholder codes. Encode action.display.qrCode exactly as received using a local QR library; it is not an image URL. The buyer scans the code from another device or enters shortCode in the Metropol app on the same phone. Preserve leading zeros. Do not call confirm or resend for a DISPLAY action.

Track the result from your merchant server through GET /payments/:id and your existing payment webhook flow. Mark the order as paid only after the platform reports a definitive successful status. PROCESSING and NEEDS_RECONCILIATION remain pending or uncertain.

Accept a payment through Checkout Form

Use your existing Checkout Form integration. Selecting Meal Card → Metropol Kart sends POST /payments/form/payment with the checkout token and session proof:

{
  "token": "<checkout-token>",
  "checkoutSessionProof": "<session-proof>",
  "paymentMethod": "MEAL_CARD",
  "mealCard": { "providerCode": "METROPOL" },
  "browserFingerprint": "<browser-fingerprint>",
  "paymentChannel": "WEB"
}

Do not add amount, order or buyer details: the platform reads them from the checkout record. The form displays the QR code, short code and expiry countdown. Re-rendering or switching away and back does not create another QR payment.

Even when Metropol is the only meal-card provider, the buyer first selects Metropol Kart. Opening the Meal Card section alone does not create a QR payment request.

The form reads persisted payment state using POST /payments/form/payment/status:

{
  "token": "<checkout-token>",
  "checkoutSessionProof": "<session-proof>"
}

The response data contains the payment identifier, status and any open action. This endpoint does not initiate a payment or call Metropol; server-side jobs query the provider. Provider credentials and merchant Bearer tokens never enter the browser.

After a definitive successful payment, the form POSTs the signed fields in data.merchantCallback once to the valid callbackUrl saved on the intent, using the existing callback signature contract. Without a callback URL the success message remains in the form; pending or uncertain results do not trigger a success return.

Expiry and uncertain outcomes

Use expiresAt for code expiry. Hide the code when it expires and keep tracking the payment; the countdown is not proof of a failed payment. A network error, incomplete response or provider “not found” response does not justify starting another charge. Do not rely on the provider to deduplicate repeated QR creation with the same reference.

To stop new payments, disable the Meal Cards method in Form Settings or disable the Metropol connection. Queries, authorized refunds and API reconciliation for its existing payments continue; the disabled connection is excluded from new payment routing. Deleted connections and unavailable provider secrets cannot be recovered this way.

Cancellation and refunds

For payments collected through either API or Checkout Form, use Refund on the payment details page or the existing refund contract from your merchant server: POST /payments/:id/refund. A panel session or signed API request, payment:refund permission and an Idempotency-Key are required. The body must include paymentIntentId matching the payment ID in the URL. Omit amount to refund the remaining balance. Partial-refund example:

{
  "paymentIntentId": "<payment-id>",
  "amount": "2500",
  "reason": "One item returned"
}

This refunds TRY 25.00. Cumulative partial refunds cannot exceed the captured amount. Use a different key for a new refund and the same key for retries of that request. Metropol classifies a full return within the same batch as cancellation and other returns as refunds; both use this refund flow and ReturnType=1. The platform records the refunded amount and emits the existing refund webhook. /void releases preauthorization and is not used for Metropol QR payments. Technical reversals (ReturnType=2) are not sent. Checkout Form does not initiate refunds from the buyer’s browser.

An uncertain refund or cancellation remains in reconciliation; do not try another key for the same payment. A successful sale inquiry does not prove a refund. Metropol does not document a separate return inquiry, so a lost response may require provider confirmation. Track the payment record and existing refund webhooks.

Daily transaction reconciliation

Select API reconciliation for the Metropol connection in the panel. The platform automatically fetches closed business days, validates every page and matches only web payments whose ownership is proven by its stored context. Physical POS or external transactions in the same merchant-wide report are not assigned to web payments. Amount/status discrepancies open operations cases.

This is transaction evidence, not confirmation of commission, net payout or a bank transfer. It never releases payouts automatically. When the provider omits a timezone, the indexed record has report-day precision. Historical API reports also support disabled connections; retain the reconciliation selection and access to provider secrets. Live support remains disabled pending provider acceptance.

The Provider transaction reports section of the reconciliation panel shows the report day, processing phase, last successful run and error/retry information. It previews the latest 50 observations with terminal, reference, amount and ownership; discrepancies use the existing case workflow. Unassigned rows of shared platform accounts are not exposed to other merchants.