Integration Guide: Paygreen Meal Vouchers

1. Find the Paygreen Payment Method

Call List Payment Methods (GET /payment_methods) for the restaurant and channel of the order, and pick the entry whose code is Paygreen. Its paymentMethodId is the value to send in payments[]. The payment method must be enabled for the consumption mode of the order, otherwise POST /orders answers payment_method_not_activated (403).

2. Create the Order - the Metadata Contract

Create the order with POST /orders (see Create Orders for the full request body). The payment entry carries a metadata field, which must be a JSON-encoded string with the following keys:

{
  "restaurantId": 2285,
  "channelId": 2,
  "consumptionMode": "MODE_TAKE_AWAY",
  "menuId": 24194,
  "cart": [
    {
      "productId": 1670891,
      "quantity": 1,
      "steps": []
    }
  ],
  "expectedAt": "2026-09-15T12:30:00.000Z",
  "payments": [
    {
      "paymentMethodId": 169093,
      "amount": 3150,
      "quantity": 1,
      "metadata": "{\"paygreenPaymentType\":\"TRD\",\"firstName\":\"Alice\",\"lastName\":\"Martin\",\"email\":\"alice.martin@example.com\"}"
    }
  ]
}

{
  "status": 200,
  "code": "required_action",
  "message": "Additional action required.",
  "data": {
    "orderId": 1927055,
    "requiredAction": {
      "type": "paygreenPaymentToProceed",
      "transactionId": "po_3f9c2a1b7d8e4c5f9a1b2c3d4e5f6a7b",
      "paymentUrl": "https://payment.paygreen.fr/po_3f9c2a1b7d8e4c5f9a1b2c3d4e5f6a7b",
      "result": {
        "status": "payment_order.pending",
        "threeDSecureStatus": null,
        "paymentErrorStatus": null
      }
    }
  }
}

3. Send the Customer to the Payment Page

Open requiredAction.paymentUrl for the customer, either as a full-page redirect or inside an iframe. Always use the URL returned by the API, never build it yourself. The customer selects the voucher network, pays the eligible part with vouchers and any remainder by card, all on the Paygreen page.

The return and cancel URLs are fixed by Innovorder: after paying or cancelling, Paygreen sends the customer back to an Innovorder-hosted page whose only job is to post a window.postMessage to its parent window. It is therefore designed for the iframe integration:

window.addEventListener('message', (event) => {
    if (event.data?.id === 'paygreen-insite') {
        // Customer came back from the payment page.
        // event.data.message = { pid: 'po_...', result: 'payment_order.successed' | ..., orderId: '1927055' }
        closePaymentIframe();
        startPollingOrder(event.data.message.orderId); // step 4 - the order status is the only proof of payment
    } else if (event.data?.id === 'close-modal') {
        // Customer cancelled on the payment page: the order will end refused.
        closePaymentIframe();
    }
});

With a full-page redirect the customer lands on that (blank) Innovorder page: prefer the iframe, or keep your own "waiting for payment" screen open in a first tab and poll the order from there (step 4). In both cases, treat the message only as a signal to start polling, never as the payment confirmation.

4. Wait for the Confirmation

Paygreen notifies Innovorder by webhook when the Payment Order reaches its final state. Until then the order is awaiting action and unpaid, and it is not yet part of the order read endpoints: GET /v1/orders/{orderId} answers omnichannel_order_not_found (400) in the meantime.

1. Poll Get Order Details (GET /v1/orders/{orderId}) every few seconds with the orderId of step 2, until it returns the order with status PAID. Ticket, kitchen and customer notifications are triggered at that very moment.
2. If Paygreen reports the payment as refused, expired or cancelled, the order is set to refused and never appears in the order endpoints. Create a new order for a retry; do not reuse the orderId.
3. Give up after the lifetime of the Paygreen payment page (a few minutes): a customer who never came back leaves an expired Payment Order and a refused order behind, nothing to clean up on your side.