ZyloPaydocs

Payer confirmation (requires_action)

Why some taps are held until the customer confirms in the ZyloPay app, and how to handle it.

Some payments are held after the tap until the customer confirms them on their phone. This is ZyloPay's step-up check. It protects the customer if a pass is used by someone else.

While held, the payment intent is requires_action and next_action describes the request:

"next_action": {
  "type": "payer_confirmation",
  "reason_code": "FIRST_MERCHANT_PAYMENT",
  "expires_at": "2026-09-28T14:03:31.000Z"
}

Why a payment is held

reason_codeMeaning
AMOUNT_ABOVE_THRESHOLDThe amount is above the confirmation threshold ZyloPay sets for the network.
RISK_FLAGGEDZyloPay's risk rules flagged the payment.
FIRST_MERCHANT_PAYMENTThe customer's first payment at your store, when the risk policy asks for it.
CUMULATIVE_LIMITSeveral unconfirmed payments since the customer's last confirmation reached a limit.

The thresholds are ZyloPay risk settings, not merchant settings. Treat the list as open: new reason codes may appear.

What happens

  1. The terminal shows that it is waiting for the customer.
  2. The request appears in the ZyloPay payer app, where the customer approves or denies it. It expires after 60 seconds. ZyloPay sends no push notification or SMS for it: the customer confirms in the app, so staff may need to ask them to open it.
  3. Confirmed: the payment settles through the same path as any other: processing if needed, then succeeded.
  4. Declined or expired: the intent becomes canceled with cancellation_reason step_up_denied or step_up_expired, and payment_intent.canceled is sent. Nothing is charged.

The cashier can cancel from the terminal while the request is open (cancellation_reason: "canceled_at_terminal"). Your server can cancel with POST /v1/payment_intents/{id}/cancel. If the customer confirmed first, a cancel answers 409 payment_intent_unexpected_state and the payment goes ahead.

What your code should do

  • Show "Waiting for the customer to confirm on their phone" when you receive payment_intent.requires_action.
  • Do not create a second intent for the same order while one is requires_action.
  • Wait for payment_intent.succeeded or payment_intent.canceled. Both arrive within about a minute.

Payment intents

A payment intent asks one terminal to take one payment. How to create, follow and cancel it.

Refunds

Full and partial refunds, where the money comes from, the limits that apply, and how idempotency keeps a refund from being sent twice.

On this page

Why a payment is heldWhat happensWhat your code should do