Overview
Two settings are required before you can take payments with the card terminal:
- Enable card terminal payment methods:In the "POS card terminal" tab of Payment Settings, choose the methods your shop accepts.
- Connect POS to the terminal:On each POS, go to "POS Settings → Card terminal", enter the terminal IP and POS-KEY, and turn on the card terminal.
Apply for a Terminal
If you do not have a card terminal yet, tap "Apply on WhatsApp" at the top of "Settings → Payment Settings → POS card terminal". Your shop name is added to the message automatically. SHOPAGE customers pay no annual fee and no terminal rental fee.
Supported Payment Methods
You can enable credit card, UnionPay card, AMEX, Octopus, PayMe, FPS, WeChat Pay, Alipay and UnionPay wallet. Available methods depend on the services activated on your terminal. Card terminal methods only appear on POS; online checkout is not affected.
Setup
Step 1: Enable card terminal payment methods
Path: "Settings" → "Payment Settings" → "POS card terminal" tab.
- Turn on payment methodsTurn on the methods you need, e.g. "Credit card (card terminal)" or "Octopus (card terminal)".
- SaveTap "Save" to apply.
Step 2: Connect the terminal on POS
Path: "POS" → "POS Settings" → "Card terminal". Each POS is set up separately.
- Enter terminal detailsTurn on the card terminal switch and enter the terminal IP and POS-KEY.
- Check the terminal certificateTap "Check terminal certificate" to open the terminal page. If the browser warns that the connection is not secure, choose to proceed. You can also download the CA certificate and install it on this device.
- Test the connectionTap "Test connection". "Connected to the terminal" means the setup is correct.
- SaveTap "Save".
Checkout Flow
On a POS with the card terminal enabled, payment methods move to the "Total" step. Card terminal methods are listed first with a "Terminal" tag, and up to 10 methods are shown by default so they can be tapped directly. POS terminals without the card terminal enabled do not show these methods.
- Select items and deliverySame as a regular POS order.
- Choose a card terminal methodIn the "Total" step, choose a card terminal method such as "Octopus (card terminal)", check the amount and submit. POS remembers the last method used.
- Wait for the customer to pay"Waiting for card terminal" appears and the amount is sent to the terminal. The customer taps, inserts a card or scans to pay.
- Order createdOnce the terminal confirms the payment, the order is created and marked as paid. Print the receipt as usual.
Cancelling a Transaction
While waiting, tap "Cancel payment". The terminal is told to cancel right away and no order is created. If the customer paid just before you cancelled, the system checks with the terminal and shows "Payment was cancelled, but the terminal shows it as paid" with the transaction number; refund it on the terminal. If the terminal times out, the system first queries the result; if the payment cannot be confirmed, the transaction is cancelled and you are asked to check the terminal's transaction history.
Create Order Manually
If POS cannot reach the terminal but the customer has already paid on it, tap "Create order manually (paid on terminal)" in the "Total" step:
- Confirm the paymentCheck on the terminal that the transaction succeeded.
- Enter the transaction number (optional)Enter the transaction number from the terminal receipt to make reconciliation easier.
- ConfirmTap "Create order". The system does not contact the terminal; the order is created and marked as paid.
Orders and Reconciliation
Orders paid through the card terminal show the following in order details:
| Field | Content |
|---|---|
| Terminal transaction no. | The transaction number returned by the terminal; for manual orders, the number entered by the cashier (if any) |
| Merchant order no. | The order number sent to the terminal; only for terminal-confirmed orders |
| Payment record | "Confirmed by terminal" or "Created manually (not confirmed by terminal)" |
To check transactions, tap "Print transaction summary" in "POS Settings → Card terminal" and the terminal prints a summary.
Common Messages
| Message | Reason | What to do |
|---|---|---|
| Please enter the terminal IP and POS-KEY first | The card terminal settings on this POS are incomplete | Fill them in under "POS Settings → Card terminal" and save |
| Cannot connect to the terminal; order not created | POS and the terminal are on different networks, the terminal IP has changed, or the browser does not trust the terminal certificate | Check the network and terminal IP, then tap "Check terminal certificate" |
| The terminal is handling another payment. Try again shortly | The terminal's previous transaction has not finished | Try again after the terminal finishes or cancels that transaction |
| The terminal did not respond; payment result unconfirmed, order not created | The terminal timed out and the system still could not confirm the payment | Check the terminal's transaction history; if paid, use "Create order manually" |
| The terminal collected the payment, but the order could not be created | The payment succeeded on the terminal but the order failed, e.g. an item was out of stock | Use "Create order manually" with the transaction number, or refund on the terminal |
| Amount must be greater than 0 to use the card terminal | The order total is 0 | Use another payment method |
FAQ
Can online customers use card terminal payment methods?
No. Card terminal methods only appear on POS terminals with the card terminal enabled. Online checkout is unchanged.
Are POS terminals without a card terminal affected?
No. They do not show card terminal methods, and their checkout flow stays the same.
Can several POS share one terminal?
Yes, but the terminal handles one transaction at a time. If another POS is collecting a payment, you will see "The terminal is handling another payment". Shops with many checkouts should pair each POS with its own terminal.
Can I refund a terminal transaction in the system?
Not yet. Refunds are made on the terminal, and the order status needs to be updated manually.
Where do I get the POS-KEY?
The POS-KEY is provided when you apply for the terminal. If you do not have it or have lost it, contact SHOPAGE customer service to find out how to get it. It encrypts communication between POS and the terminal; keep it safe and do not share it.
