Your own app on the reader

Before your app can take a payment, Electronic Payments:

1. Boards the merchant and activates the reader with the Merchant360 Payment App (2.44.2 or later), using its 8-digit activation code.
2. Sets the reader’s Terminal mode to Payment service in ISO360. In this mode the Payment App never locks the reader, never opens by itself, and shows no menu: your app is the merchant’s app.
3. Allows your app on the reader. An ISV does this itself: register the app once in the ISV portal (App settings) and switch it on for each reader on the merchant’s page (step 2).
4. Turns on what the merchant needs: keyed sales (MOTO), pre-auth, tips, the pricing program.

An ISV sets the same Terminal mode for its connected merchants’ readers in the ISV portal (Devices).

The reader serves only the apps allowed on it. Register your app once with two values:

• Your package name (your applicationId), for example com.grailpay.pos.
• The SHA-256 of the certificate your release APK is signed with. Get it with one of the commands below.

Where: the ISV portal, App settings, Register an app (or POST /isv/apps with your platform key). Then, on each merchant’s page, Your app on these readers: switch your app on for the readers it runs on (POST /isv/apps/{id}/readers). Not an ISV? Send Electronic Payments the two values and they allow it.

Add every certificate your app may carry (debug, PAXSTORE-signed). Not sure which one the reader sees? Run one sale anyway: the refusal (app_not_allowed) shows the exact certificate SHA-256 the reader saw. Add that value to the app.

1. Electronic Payments sends you m360-terminal-sdk-1.3.0.aar. Put it in your app module’s libs folder.
2. Add the line below to your app’s build.gradle.
3. Nothing else: no permission, no API key and no Handpoint library. The SDK’s manifest adds the <queries> entry Android 11+ needs to find the Payment App.

Minimum: Android 7.0 (API 24). PAX A35, A920 and A920 MAX readers run Android 10 or later.

Connect once, for example in your main Activity’s onCreate, and disconnect in onDestroy. Every listener runs on the main thread, so you can update your screen directly.

When the Payment App is updated through PAXSTORE, the connection drops for about half a minute; the SDK connects again by itself and calls onConnected again.

If onFailed runs, show the message. payment_app_not_installed and payment_app_too_old mean the reader needs the Payment App or an update from Electronic Payments through PAXSTORE.

terminal.readerSettings() tells your app how Electronic Payments set up this reader, so your screens can match it: hide your Keyed button when keyed sales are off, show the surcharge percent before the sale, put the merchant’s name and address on your receipt. Read-only; the same values the card step uses.

• Keyed: isMotoEnabled(), isCvvRequired(), isAvsRequired()
• Pre-auth: isPreAuthEnabled(), getPreAuthMinCents(), getPreAuthMaxCents()
• Tips: isTipEnabled(), getTipPercentages()
• Pricing: getPricingProgram() (none, surcharge, dual_pricing, cash_discounting, admin_fee), getSurchargePercent()
• Card step: getSignatureOnScreen(), isCancelButtonOn(), getMaxSaleCents(), getCurrency(), getLanguage()
• Receipt: getMerchantName(), getMerchantAddress(), city, state, ZIP, phone, getMidLast4(), getTerminalSerial()

Do not keep your own copy of these: if your app said keyed was on and the reader said off, the sale would be refused. setReaderSettingsListener() tells you when Electronic Payments changes them. Needs Payment App 2.45.0; on 2.44.x readerSettings() returns null.

Define your own settings for your app (up to 250) and set them for all your merchants, one merchant or one reader. Your app reads the value for its reader; there is nothing to host.

1. ISV portal, App settings, Settings for your app: Add setting. Give it a key your code uses (printKitchenTicket), a label, a type (on / off, choice, several choices, text, whole number, amount, percent), a default, and whether it can differ per reader. Or PUT /isv/app-settings/definitions/{key}.
2. Set values: Values for all your merchants on the same page; one merchant or one reader on the merchant’s page. Or PATCH /isv/app-settings/values, PATCH /app-settings, PATCH /terminal/devices/{id}/app-settings. The reader’s value wins, then the merchant’s, then all merchants, then the default.
3. In your app: terminal.partnerSettings() and setPartnerSettingsListener(). Changes reach the reader at once.

Not for passwords, keys or tokens: values are stored as entered and kept on the reader. Billing: $1.00 per reader per month, for each reader that received your settings that month, on Electronic Payments’ monthly invoice. Needs Payment App 2.46.0 and SDK 1.2.0.

Call sale() with the amount in cents and your own reference for the sale, for example your order number. Use a new reference for every sale and keep it: it is what stops a second charge (step 8).

The Payment App then comes to the front and runs the card step. The customer sees, in order:

1. The amount, with the surcharge notice when the merchant has a surcharge program (the percent is shown before the card).
2. The tip screen, if you asked for it or the merchant’s tip setting is on.
3. Tap, insert or swipe (contactless, EMV chip, magnetic stripe), with a Cancel button unless you turned it off.
4. PIN on the PAX secure keypad when the card asks, and the signature screen when the merchant’s “Signature on screen” setting asks for it.
5. Approved or Declined for 2 seconds. Then the Payment App goes to the back and your app is in front again, with the result.

The Payment App prints nothing and shows no receipt choices for your sales: your app prints or sends the receipt (step 7).

• .tipPrompt(true): the tip screen. false: no tip. Not set: the merchant’s tip setting.
• .allowKeyed(true): a Key enter card button for a card that will not read. .keyed(): open keyed entry at once (phone order). The card number is typed on the Payment App’s own secure screen, never in your app. Needs keyed sales (MOTO) on the merchant. By default the reader then asks for CVV, ZIP and street number.
• .allowCancel(false): no Cancel button on the card screen for this sale.
• .printReceipt(true): the Payment App prints or offers the receipt for this sale, for an app that cannot print. Not set: the receipt is yours to give (SDK 1.3.0, Payment App 2.46.4).
• .level2(taxCents, taxExempt, poNumber): Level 2 data for business cards.
• SaleRequest.preAuth(amount, ref): a hold instead of a sale (hotel, rental). Card read only: no tip, no keyed entry. Needs pre-auth on the merchant; the merchant’s smallest and largest hold apply.

Print the receipt on the reader’s printer with your own layout. Show at least the merchant’s name and address, the date and time, the total, the card brand and last 4, the entry method and the auth code. When there is a surcharge, show it as its own line labeled “Surcharge”.

If your app restarts during a sale, or never gets the result, do not start a new sale with a new reference. Do one of these:

• Call terminal.status(reference): the reader’s result for that reference, or null if it has none.
• Call sale() again with the same reference. If that sale already finished, you get its result again (isRepeat() is true) and the card is not charged again.

terminal.cancel(reference) stops the sale while no card was read yet. The result comes as CANCELLED with getCancelSource() = pos. A card already being read finishes, and you get its real result.

During the card step the Payment App covers the screen, so a clerk cancels with the Cancel button on that screen (the result then says terminal). Call cancel() from your code, for example when your own timer runs out or the order is voided elsewhere.

These run through the Merchant360 API with the payment id, from your server (or from Merchant360 itself). They need no card on the reader:

• POST /payments/{id}/void: undo an approved sale the same day.
• POST /payments/{id}/refund: money back after the batch closed; send amount for part of it.
• POST /payments/{id}/tip-adjust: change the tip on an approved sale.
• POST /payments/{id}/capture: charge a hold (AUTHORIZED); /void releases it.

Your server uses your platform key with M360-On-Behalf-Of (an ISV), or the merchant’s key. Never put an API key in the app on the reader. These calls are planned for a later SDK version.

1. Electronic Payments sets up a test reader (step 1) and adds your debug certificate too.
2. Run a $1.00 sale (sale(100, …)), tap a card, check the result, then void it with its payment id.
3. Run one with .tipPrompt(true), one cancelled from your app, and one status() after closing your app mid-sale.
4. Upload your release APK to your PAXSTORE developer account. PAX signs it; production PAX readers install only signed apps.
5. Electronic Payments pushes your app and the Payment App to the merchant’s readers through PAXSTORE.