One merchant's own POS or software

In Merchant360 → Developers, create a live key with only the scopes the software needs (for card readers: terminal:read, payments:read, payments:write). Keep it on a server or in protected settings, never in a web page or a shipped app.

A free m360_test_ key from the sandbox: any terminal_id works, the sale approves on GET /payments/{id}, and no money moves.

GET /terminal/devices lists the readers; save which terminal_id is at which station.

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.

POST /webhooks with your HTTPS URL. Same benefits as for an ISV: results your POS missed, and refunds or voids done elsewhere.

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.