Meal Card
Lunixi Meal Cards lets you accept payments from different meal-card providers through one API and Checkout Form. The payment method is MEAL_CARD and its request block is mealCard. Manage provider connections in the panel and offer the options enabled for your account.
Paycell PAYE and Metropol Kart are providers within this product. Customer fields, approval steps, available environments and refund rules vary by provider. Adding a provider preserves the shared payment contract; integrations that read options and fields from the methods response use the same structure.
Providers
| Provider | Customer flow | Setup and provider rules |
|---|---|---|
| Paycell PAYE | Phone and sharing consent, followed by selection from eligible PAYE cards (INPUT) | Paycell PAYE guide |
| Metropol Kart | QR or short-code approval in the provider app (DISPLAY) | Metropol Kart guide — TEST environment |
Available providers, environments and operation permissions depend on your connections. This table does not automatically connect a provider to your account. Metropol's TEST restriction applies only to the Metropol connection.
Prepare the connections
- Open Payment → POS Center → Discover → Meal Card in the panel, choose a provider and enter its connection details.
- Configure the environment and supported payment, inquiry, cancellation/refund permissions. Providers do not necessarily offer the same operations.
- In Form Settings, enable Meal Card and the provider connections you want to offer, then set their order. The methods list uses these settings for direct API integrations too.
- Complete any additional server-side order/customer requirements in the provider guide.
Keep provider credentials in connection settings. Never include them in the buyer form or the payment request's mealCard block.
Accept a payment through the API
First call GET /payments/methods?paymentMethod=MEAL_CARD from your merchant server. Its providers[] entries include provider codes, inputFields, actionTypes, currencies and amount limits. A disabled method or no eligible connected provider returns an empty methods list.
- Follow the returned
providerSelectionModeandproviderSelectioncontract when choosing a provider. - Use a returned provider code for
mealCard.providerCode; do not hard-code the provider list. - Add the chosen provider's
inputFieldsvalues tomealCardusing the declaredkeynames. Prepare any server-side order data required by its guide as well.
Start the payment through POST /payments/direct/payment using the existing Bearer and request-signing contract. Idempotency-Key is required; reuse the same key for retries of the same request.
{
"paymentMethod": "MEAL_CARD",
"amount": "10000",
"currency": "TRY",
"orderId": "ORDER-MEAL-001",
"mealCard": {
"providerCode": "<provider code from the methods response>"
},
"basketItems": [{ "id": "ITEM-1", "name": "Service fee", "category1": "Service", "itemType": "VIRTUAL", "price": "10000" }],
"buyer": { "name": "Ada", "surname": "Yılmaz", "identityNumber": "11111111111", "email": "[email protected]", "gsmNumber": "+905000000000", "city": "Istanbul", "country": "Turkey", "zipCode": "34732", "ip": "203.0.113.10" },
"billingAddress": { "contactName": "Ada Yılmaz", "address": "Altunizade Mah. Örnek Sok. No: 1", "city": "Istanbul", "country": "Turkey", "zipCode": "34662" }
}This example is the shared request body; add the provider's required fields. amount is a minor-unit digit string: "10000" means TRY 100.00. If the methods response supplies an optionId for a specific connection, send it at the top level. See Payment for the complete common request fields.
Handle the customer action
The start response's data.action tells you what the buyer must do next. Do not assume every meal-card provider uses QR; handle the returned action.type.
| Action | UI behavior | Example provider |
|---|---|---|
INPUT | Render action.input.fields; send the selected/entered values in fields using the existing confirm contract | Paycell PAYE card selection |
DISPLAY | Display the QR/short code and expiry from action.display; do not call confirm or resend | Metropol Kart |
Other supported actions and shared fields are described in Payment — Actions. Creating an action or making a selection does not by itself confirm a charge. Track GET /payments/:id and existing webhooks from your merchant server; mark the order as paid only after a definitive successful result.
Accept a payment through Checkout Form
Use your existing Checkout Form integration. The form lists enabled Meal Card providers, then displays the chosen provider's fields and customer action. Selecting Metropol uses QR/short codes; selecting PAYE uses its input and card-selection flow. Prepare provider-specific server requirements before opening the form.
The form starts the payment through POST /payments/form/payment with the existing checkout token and session proof:
{
"token": "<checkout-token>",
"checkoutSessionProof": "<session-proof>",
"paymentMethod": "MEAL_CARD",
"mealCard": { "providerCode": "<selected provider code>" },
"browserFingerprint": "<browser-fingerprint>",
"paymentChannel": "WEB"
}Add the chosen provider's required method fields to this shared body. Do not redefine amount, order or buyer data in the form request; the platform reads them from the checkout record. Merchant Bearer tokens and provider credentials must never enter the browser.
Opening Meal Card shows a provider choice with its name and logo, even when only one provider is available. The QR payment request starts after the buyer selects that provider.
The form reads persisted payment state through POST /payments/form/payment/status with token and checkoutSessionProof. Its response contains the same payment identifier, status and any open action; reading status never starts a new payment.
For a definitive AUTHORIZED/CAPTURED result with a valid callbackUrl saved on the intent, data.merchantCallback contains { url, method: "POST", fields }. The form submits the signed fields unchanged once and navigates to the result page. Without a callback URL, the success message remains in the form. The callback is informational; verify payment on your server through webhooks or GET /payments/:id.
Cancellation and refunds
Manage payments collected through API or form in the existing panel transaction screen and Refund API. For POST /payments/:id/refund, paymentIntentId must match the payment ID. An authorized panel session or signed merchant API request, payment:refund permission and Idempotency-Key are required.
Full/partial refund support, same-day cancellation rules and the applicable operation vary by provider. Follow the connection permissions and provider guide rather than applying one provider's rules to another. The buyer's checkout browser does not initiate refunds.
Reconciliation and uncertain outcomes
Enable a supported reconciliation type on the provider connection. Track transactions in the shared reconciliation screen; each provider guide describes report coverage, dates and refund-matching rules. A transaction report alone does not prove a bank payout or net settlement.
Do not start another payment for PROCESSING or NEEDS_RECONCILIATION outcomes. Network errors and customer-action expiry do not prove payment failure; keep tracking the existing payment. If a refund result is uncertain, do not send a second refund with a new key.