Error handling

Every function of the SDK throws a LemonwayTerminalError. Branch on its code: codes are stable across versions.

import { LemonwayTerminalError } from '@lemonway/terminal';

try {
  await LemonwayTerminal.collectPayment(authorized);
} catch (error) {
  if (error instanceof LemonwayTerminalError) {
    switch (error.code) {
      case 'PAYMENT_DECLINED':
        // ask for another card, with a new Payment Order
        break;
      case 'NETWORK_ERROR':
        // check the Payment Order on your backend before retrying
        break;
    }
  }
}

Property	Description
`code`	Stable error code, listed below.
`message`	Human-readable message, in English. Log it; do not show it as is to the merchant.
`status`	HTTP status, when the PayGreen API answered with an error.
`cause`	Original error, for your logs only.

Error codes

Setup

Code	Cause	What to do
`NOT_INITIALIZED`	`init()` not called, `<LemonwayTerminalRoot>` not mounted, or still initializing.	Call `init()` first and wait for `terminal.ready`.
`INVALID_CONFIG`	Missing or invalid option in `init()`, or public key rejected by the API (HTTP 401).	Check `env`, `publicKey` and `tokenProvider`. Keys and `env` must match.
`INITIALIZATION_FAILED`	The terminal could not start, for example a refused permission.	Remount `<LemonwayTerminalRoot>` to retry.
`CONNECTION_TOKEN_FAILED`	`tokenProvider` failed, timed out (15 s) or returned no `secret`.	Check your connection token endpoint.
`INVALID_PARAMS`	Missing parameter, or no location for the connection.	Fix the call. Return `locationId` from `tokenProvider`.

Phone and reader

Code	Cause	What to do
`DEVICE_NOT_SUPPORTED`	The phone or its OS version cannot run Tap to Pay.	Use a supported phone.
`INSECURE_ENVIRONMENT`	Debug build, Developer options on, or rooted phone.	Use a release build and turn Developer options off.
`PERMISSION_REQUIRED`	Location services off or permission refused.	Ask the merchant to turn location on and grant it.
`NFC_DISABLED`	NFC is off.	Ask the merchant to turn NFC on.
`READER_DISCOVERY_FAILED`	The phone could not be found as a reader.	Retry `connectTapToPay()`.
`READER_CONNECTION_FAILED`	Connection refused, for example Tap to Pay not enabled on the account.	Retry. If it persists, contact PayGreen with `error.message`.
`READER_DISCONNECTED`	The reader was disconnected.	Wait for `reader.connected` or connect again.
`READER_HARDWARE_ERROR`	The reader failed.	Retry.

Payment

Code	Cause	What to do
`PAYMENT_ORDER_FAILED`	The API refused to authorize the Payment Order. See `status` below.	Usually create a new Payment Order.
`PAYMENT_DECLINED`	The card was declined.	Create a new Payment Order and ask for another card.
`PAYMENT_CANCELED`	The payment was canceled.	Create a new Payment Order for the next try.
`CARD_READ_ERROR`	The card could not be read.	Call `collectPayment()` again with the same `authorized` object.
`PAYMENT_IN_PROGRESS`	A payment is already running.	Wait for it, or cancel it.
`NETWORK_ERROR`	Network failure, timeout or server error.	Before `collectPayment()`: retry. During `collectPayment()`: check the Payment Order on your backend first, the card may have been charged.
`UNSUPPORTED_OPERATION`	Feature not available with Tap to Pay.	—
`UNKNOWN`	Anything else.	Same as `NETWORK_ERROR`. Log `error.message`.

authorizePaymentOrder() HTTP errors

HTTP	Code	Meaning
401	`INVALID_CONFIG`	Public key rejected, or wrong `env`.
403	`PAYMENT_ORDER_FAILED`	Wrong `objectSecret`, or Payment Order of another shop.
404	`PAYMENT_ORDER_FAILED`	Unknown Payment Order id.
409	`PAYMENT_ORDER_FAILED`	The Payment Order is locked by another request. Retry.
422	`PAYMENT_ORDER_FAILED`	Business rule: Payment Order expired or not `pending`, not `tap_to_pay`, has a buyer, or no usable `bank_card` config.
5xx, timeout	`NETWORK_ERROR`	Retry. Authorizing the same Payment Order twice is safe.

Troubleshooting the first setup

INSECURE_ENVIRONMENT on Android

Tap to Pay refuses debuggable builds and phones with Developer options on. Build a release APK, install it with USB debugging on, then turn Developer options off and open the app from its icon.

PERMISSION_REQUIRED or terminal.error at startup

Tap to Pay needs location services on and the precise location permission. If the merchant refused it, they must grant it in the system settings, then you remount <LemonwayTerminalRoot>.

iOS build fails to sign

The Tap to Pay entitlement is not enabled on your App ID yet. Request it from Apple, or set iosTapToPayEntitlement to false in the Expo plugin until then.

INVALID_PARAMS: locationId is required

Your connection token endpoint does not return locationId. Return location_id from the API as locationId, or pass it to init().