Introduction

The Terminal SDK (@lemonway/terminal) is a React Native library that turns the merchant's phone into a card terminal with Tap to Pay on iPhone and Android. The customer taps their card or wallet on the phone, and the payment goes through a PayGreen Payment Order.

Your app never handles card data and never holds a secret key.

🚧
Beta
The SDK is in beta (0.1.0-beta.x). Its API can still change between beta versions.

Core concepts

Concept	What it is
💳 Payment Order	Created by your backend with `source: tap_to_pay`. It fixes the amount.
🔑 Object Secret	Returned once when the Payment Order is created. Lets the app authorize that Payment Order only, with your public key.
🟢 Public Key	Identifies your shop in the app (`pk_…`). Safe to ship in the app.
🔒 Secret Key	Used by your backend to get a JWT. Never ship it in the app.
📡 Connection token	Short-lived token that opens a Tap to Pay session. Your backend requests it; the SDK asks your app for it through `tokenProvider`.
📍 Location	The shop's Tap to Pay location (`tml_…`). Returned with the connection token.

Payment flow at a glance

sequenceDiagram
    participant B as Your backend
    participant A as Your app + SDK
    participant P as PayGreen API
    B->>P: Create Payment Order (JWT, source tap_to_pay)
    P-->>B: id + object_secret
    B-->>A: id + object_secret
    A->>P: authorizePaymentOrder() (public key + object_secret)
    P-->>A: authorized payment
    A->>A: collectPayment(): the customer taps
    P-->>B: Webhook payment_order.tap_to_pay.*

Your backend creates the Payment Order. The amount is decided there, never in the app.
The app authorizes it with authorizePaymentOrder(), then collects the card with collectPayment().
Your backend confirms the payment from the webhook. SDK events only drive the UI.

Before you start

👍
Make sure you have:

A validated account on app.paygreen.fr with an enabled bank_card payment config. Tap to Pay needs nothing else.

Your public key and secret key (Keys page).

A React Native app, with Expo (development build) or the React Native CLI.

A supported phone: see Device requirements.

Integration steps

Getting Started: install the SDK and set up the native project.
Backend integration: create Payment Orders and serve connection tokens.
Init and connect: initialize the SDK and connect the phone.
Payment Flow: take payments.
Confirm payments: listen to webhooks on your backend.
Error handling and Events: build the UI around them.