A POS for many merchants (ISV)

Electronic Payments creates your partner record and sends your platform key through a secure share (shown once). Then, for each merchant:

• We connect the merchant to you. It appears in GET /accounts at once.
• We register and activate its readers, and set them to POS Listener.
• We set what the merchant allows: keyed sales, pre-auth, refunds, tips, and the receipt rule (below).

You send us your logo (PNG, JPEG or WebP, up to 2 MB, wide, transparent background) for the bottom of the waiting screen.

Store it in a secrets manager or your host’s encrypted environment variables and read it when the service starts. Never in the POS app, on a store PC, on the reader, in source control, chat, email or logs: anyone holding it reaches every connected merchant.

Each POS station calls your server; your server calls Merchant360. No server of your own? Use the POS with no server guide instead.

• Authorization: Bearer m360_isv_…
• M360-On-Behalf-Of: the merchant the call is for: its id from GET /accounts, or its MID. Never the business name (names repeat). Not sent on GET /accounts.
• Idempotency-Key on every POST (your order or ticket id).

Base URL: https://www.merchant360.com/api/m360/v1

Get a free test key at cygma.cloud/merchant360/sandbox. With a test key any terminal_id works, GET /payments/{id} approves the sale (amount: 4100 declines, to test a decline), and no money moves. A test key belongs to one test merchant, so leave M360-On-Behalf-Of out while testing.

GET /accounts lists every merchant connected to you with its id. Save the id with the store in your setup. This is a lookup, not part of a sale.

GET /terminal/devices lists the store’s readers. Save which terminal_id sits at which POS station (the serial is on the label under the reader). A good home for both lookups is an “Import card readers” button in your store setup.

POST /payments with the amount in cents and the terminal_id of the reader at that station. Merchant360 hands the sale to that reader: it leaves its waiting screen, shows the amount and asks for the card (tap, chip or swipe). Card data never reaches your software.

Always send terminal_id: it is how Merchant360 knows which reader to wake. Left out, the sale goes to the merchant’s default reader, which is wrong for a store with two stations.

You get 202 at once, with status: "pending" and a payment id starting tp_. Save the id.

Ask for the payment every 2 to 3 seconds until its status is no longer pending:

• succeeded: approved. amount is what was charged (with any tip or fee the merchant’s pricing adds on the reader); card has the brand and last 4.
• failed: declined.
• canceled: cancelled on the reader, or by you.

A sale is never cancelled on a timer. One still pending after 360 seconds is flagged for review and stays pending.

• POST /payments/{id}/cancel: stop a sale still waiting for the card. If the card was charged just before, it is voided.
• POST /payments/{id}/void: undo an approved sale the same day, before the batch closes.
• POST /payments/{id}/refund: money back after the batch closed. Send amount for part of it.
• POST /payments/{id}/tip-adjust: add or change a tip on an approved sale.

Send an Idempotency-Key (your order or ticket id) on every POST. If the answer is lost (timeout, restart, Wi-Fi drop), send the same POST again with the same key: you get the same payment back, never a second sale. Then read its status as in the previous step.

• terminal_options.allow_cancel: false: no Cancel Sale button on the reader for this sale.
• terminal_options.print_receipt: true: the reader prints or offers the receipt for this sale, for a register with no printer. false: your POS prints and the reader goes back to its waiting screen. Left out: the terminal’s setting (Payment App 2.46.4 or later).
• terminal_options.allow_keyed: true: a Key enter card button, for a card that will not read. Needs keyed (MOTO) sales on the merchant; the reader then asks for CVV, ZIP and street number by default.
• tip: { prompt: true }: the tip screen on the reader.
• POST /payments/authorize with the same body: a hold instead of a sale, captured later with /payments/{id}/capture or released with /void. Needs pre-auth on the merchant.

Polling alone works. A webhook adds three things: a result still reaches you when your request or POS dropped; refunds and voids done outside your POS (in Merchant360 or on the reader) reach you; and one endpoint covers every merchant without spending your 1,200 requests a minute on polling.

Register once with POST /webhooks using the platform key. Keep the secret it returns (shown once) and check the M360-Signature header on each delivery. Answer 2xx fast; the same event can arrive twice, so handle it by its id.

Every error is { "error": { "message", "code" } }. Most refusals name a setting, not an outage: show the code to your user instead of “contact support”.

• 403 no_grant: the merchant is not connected to you.
• 403 insufficient_scope: your key is not granted that kind of call.
• 403 billing_tools_off: the merchant’s Billing Tools are off.
• 403 not_permitted_by_channel: reports or refunds are off for partners on that merchant.
• 409 terminal_unavailable: no card readers on the account.
• 422 moto_not_enabled / 422 preauth_not_enabled: keyed sales / pre-auth are off for the merchant.
• 429 rate_limited: too many requests in the minute.
• 500: ours. Send us the time and your reference.

1. With the platform key: GET /accounts shows the merchant; GET /terminal/devices shows its readers.
2. A $1.00 sale (amount: 100) on one reader; tap a card; read it as succeeded.
3. POST /payments/{id}/void, then send us the payment id so we confirm it on our side.