Merchant360 API

JSON over HTTPS. All amounts are integers in cents unless noted. Timestamps are ISO 8601 (UTC). Base URL:

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

Every write accepts an optional Idempotency-Key header, and every list is paginated. Object responses include an object field naming the type. A machine-readable OpenAPI 3.1 spec lives at GET https://www.merchant360.com/api/m360/v1/openapi.json.

▶ See every tool working live on the examples page.

The integration wizard asks what your software does and returns the ordered list of endpoints to code to, with links into this reference. The short version:

Gift cards: Gift. Level II / III data: Level II & III (keyed and card-on-file charges). Tips on the reader: Tips. Keyed entry from your POS: Keyed entry.

Create a key in Merchant360 under Developers & API (owner only). Send it as a bearer token on every request:

Authorization: Bearer m360_live_xxx

Keys are per-merchant, scoped, and rate-limited. Missing scope → 403. GET /me echoes the key’s merchant, scopes, and mode.

Two kinds of key use this header. A merchant key (m360_live_ / m360_test_) belongs to one merchant and needs nothing else. A platform key (m360_isv_) belongs to a technology partner and is the bearer token on every request the partner makes; the merchant the call is for is named in a second header, M360-On-Behalf-Of. See Platform keys (ISV).

No merchant yet? Grab a self-serve test key from the sandbox to build against payments, the card vault, hosted fields, checkout, gift cards and loyalty in test mode.

Grant a key only what it needs. :read permits GET, :write permits create/update/delete.

Keys prefixed m360_test_ run in sandbox: requests are validated and shaped exactly like live – payments, tokens, hosted fields, Checkout Sessions, and ACH all simulate end-to-end – but no money moves and no gateway/bank call is made. Test-mode activity is kept separate from the merchant’s live Transactions. Switch to a m360_live_ key to move real money.

Self-serve sandbox keys carry payments:*, cards:*, checkout:*, egift:*, loyalty:* and terminal:read. Gift and loyalty test cards: a number ending 0000 is not found (404); gift balance 2500 cents; 1000 points; a card ending 1111 holds 0 points; redeeming more points than the balance returns 402. See Gift cards and Loyalty. Card-present test sales: Card-present sale.

Test cards. Use any future expiry and any CVV. Unknown card numbers approve with a full AVS match; these exercise each decline and AVS path (declines return 402 with decline_code; test approvals carry avs_result):

The same numbers work on every test-mode surface – the API, hosted Checkout Sessions, and plugin test connections. A card_token containing the word decline also simulates a decline.

Test objects are unmistakable by id prefix – test_txn_ (payments), test_auth_ (authorizations), test_ach_ / ach_test (ACH), card_test_ (saved cards), test_re_ (refunds).

To build card-present, you need a reader. A developer kit is a debug PAX A920 MAX or A920 Pro connected to the Handpoint staging gateway. Electronic Payments registers the device on that gateway and connects it to a Merchant360 developer account: API calls with that account’s key reach the reader and run real card reads against test hosts. No money moves.

1. Get a test key in the sandbox. Test keys simulate a reader: send terminal_id: "TEST/SIM0001" on POST /payments and build the whole flow before the device arrives.
2. Request a developer kit on the wizard’s setup step. EPI sales confirms the model, price and shipping.
3. Connect it to Merchant360. Get the 8-digit activation code from EPI, or from the ISV portal (Devices, Activation code). On the reader open Settings, Connect to Merchant360, and enter the code. The reader then appears in GET /terminal/devices and in the ISV portal.
4. Go live with a production reader, a live key (m360_live_ or an ISV platform key), and a boarded merchant. A debug unit stays on staging.

Every error – validation, auth, decline, rate limit – comes back in the same envelope: { error: { message, code } }. The code is a stable machine-readable string that derives from the HTTP status (400 → bad_request, 401 → unauthorized, 402 → payment_declined, and so on), so you can branch on either the status or the code. message is human-readable; log it, don’t parse it.

A declined card is an error, not a status: POST /payments returns 402 payment_declined with a decline_code saying why, and no payment object is created. Some 4xx responses carry a more specific code than the table above (e.g. 422 idempotency_mismatch, 409 already_settled) – those are called out on the endpoints that raise them.

Send an Idempotency-Key header (any unique string, e.g. a UUID) on any POST. The request runs once per (merchant, key): once the original finishes, a retry with the same key replays the stored response instead of acting again. While the first attempt is still in flight, a concurrent duplicate returns 409 idempotency_in_progress; back off briefly and retry to receive the stored result. Reusing a key against a different method or path returns 422 idempotency_mismatch – mint a fresh key per logical operation.

Idempotency-Key: 8f14e45f-cea1-4a3d-9f2e-1b2c3d4e5f60

Each delivery is a POST whose body is an event envelope – { "id": "evt_…", "object": "event", "type": "payment.succeeded", "created": "…", "merchant_id": "…", "data": { … } } – where data is the full object the event is about (a payment, an ach_payment, a checkout session, …), so you rarely need a follow-up GET. Two headers ride along:

M360-Signature: t=<unix>,v1=<hex>
M360-Event: payment.succeeded

Verify by computing HMAC_SHA256(secret, `${t}.{raw_body}`) with your whsec_ secret and comparing to v1 – sign the raw body bytes, before any JSON parsing.

Respond 2xx quickly and do your work async. Anything else – including a timeout – is retried with backoff at roughly 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, and 12 h, up to 8 total attempts. Delivery ordering is not guaranteed (a retried ach.queued can arrive after ach.settled), and retries mean you can see the same event twice – process events idempotently by id. Endpoints must be https.

Terminal-keyed sales: the data of a payment.succeeded fired by a virtual-terminal or Handpoint sale carries origin (EMBED_VT / EMBED_HP / M360_VT / M360_HP / ISO_VT) and embed_key_id – an embedding integration should keep events whose origin starts with EMBED_ and whose embed_key_id matches its own key, and drop the rest.

Every event payload includes a top-level merchant_id naming the merchant it belongs to – most useful for platform (ISV) webhooks, which receive events across many merchants on one endpoint.

▶ Try the live webhook inspector – fire signed events and watch them verify.

Card payments are synchronous – the response you get back is the final answer, and there is nothing to poll. A successful charge returns 201 with status: "succeeded"; the funds are committed to the merchant’s next settlement batch. A decline is not a status: it surfaces as a 402 error with code: "payment_declined" and a decline_code telling you why, and no payment object is created. On GET /payments, status is the derived succeeded or failed, plus a settled boolean that flips once the batch settles.

You don’t need webhooks to confirm a card charge – but payment.succeeded fires on every successful sale (and card.created when save_card vaults the card), which is the clean feed for reconciliation and for systems that don’t sit on the request path.

Origin attribution. Sales keyed on a Merchant360 terminal carry an origin on the payment object – so software embedding the Embedded Terminal can pull ONLY its own sales and ignore activity that originated elsewhere. Values:

GET /payments accepts ?origin=EMBED_VT and ?embed_key=<key id> filters, and every row serializes origin + embed_key_id (null on flows that aren’t terminal-keyed – invoices, pay links, API charges – which identify by their own objects/events instead).

Present the card ONE of four ways: a keyed card, a saved card_token (a card on file – see Cards), a card-present card_present capture from a terminal or mobile SDK, or a terminal_id that sends the sale to the merchant’s card reader (see Card-present overview). Exactly one is required.

Card-present (preview). card_present carries the EMV kernel output – emv_data is the DE 55 ICC TLV payload (hex), track_2 the chip’s track-2 image, ksn the DUKPT Key Serial Number for encrypting readers – and M360 forwards it to the Cygma host as ICCSystemRelatedData / Track2Data / KeySerialNumber with the matching POSEntryMode. Test keys simulate approvals today; live keys return card_present_unavailable (503) until EMV certification and the P2PE decryption key are in place – contact EPI to join the pilot.

The response returns the saved card as card_token; vault_token is kept as a back-compat alias for the same value. With surcharge: "auto" no reusable token is returned – vault the card via POST /tokens when you need both. surcharge: "auto" composes with line_items – a surcharged sale still carries the Level III packet.

Card networks price commercial cards (business / corporate / purchasing) by how much transaction data is submitted – the three data levels below. You send the business data on POST /payments; the gateway assembles and transmits the full processor packet. Nothing else changes about the call.

How it comes together – you send vs the gateway adds

Rules that matter

• Amounts must reconcile. amount (the charge) = line totals + freight + sales_tax. The example: $89.99 + $5.95 + $7.76 = $103.70.
• Max 15 line items – the processor limit. Longer orders: send the 15 largest lines; totals still reconcile via the header amounts.
• Send Level III only on full payments. A partial payment can’t reconcile to the line items – send sales_tax (prorated) alone and it qualifies at Level II.
• Consumer cards are unaffected. The extra data is ignored on non-commercial cards – always safe to send.
• Qualification is decided at settlement, not authorization. The approval response looks identical either way; the qualification level appears in the merchant’s interchange detail.
• Works with surcharge: "auto" and on invoice payments (invoice line items carry Level III automatically when the invoice is paid in full).

An industry addendum describes what was bought, in the vocabulary the card networks defined for that trade – gallons and a pump price for fuel, arrival and departure dates for a hotel, a ticket number and an itinerary for an airline. It is the same mechanism as Level III: the charge approves either way, and the data qualifies the transaction for the industry interchange rate.

Send it as an industry object on POST /v1/payments. type names the industry; every other key is one of that industry’s fields. M360 validates the object, scales each value to the implied decimals its field uses, pads it to width, and adds the IndustryIndicator the processor needs. You send readable values – "4.2980", "2026-09-01" – and never a zero-filled integer.

Rules that matter

• Unknown field names are rejected. A typo returns a 400 naming the field rather than being dropped. Dropping it would authorize the sale, miss the industry rate, and leave you nothing to debug – the failure would show up weeks later in an interchange statement.
• Money and quantities are decimal STRINGS ("3.4900"), unlike amount which stays an integer number of cents. The scales differ per FIELD, and a single fuel object carries three of them – unit price to four places, quantity to three, the sale amount to two. M360 reads the scale off the field definition so you never have to; send the number as you would write it.
• Dates are YYYY-MM-DD and times are HH:MM.
• An empty addendum is rejected. Naming an industry and sending no fields tells the processor to expect a hotel and then describes none. Send at least one field or omit industry entirely.
• Keyed charges only – with or without surcharge: "auto". A card_token charge has no packet hook for the addendum today.
• Not every brand carries every industry. Where a profile or a field is defined by only some networks, the tables below say so, and M360 omits it on a card outside that set rather than sending data the network will not read. The clearest case is fuel: "FUEL" is the Mastercard and Discover profile, and Visa fuel data rides "FLEET" – there is no separate Visa fuel profile. Send the one that matches the card.
• Consumer cards are unaffected – the extra data is ignored, so it is always safe to send.
• Qualification is decided at settlement, not authorization. The approval looks identical either way.

Fuel and fleet product codes come from the Visa Fleet 2.0 tables, which are a different catalogue from the NIGP commodity codes used by Level III – and the fuel and non-fuel tables are separate namespaces from each other, so the same two characters mean different things in each. The full tables, with Conexxus equivalents: visa-fleet-product-codes.xlsx.

The industry dictionary also enumerates Visa Limited Data, Mail order / telephone order, Retail, Temporary services. Those are classifications rather than data sets – they carry no fields, so there is nothing to send.

Authorize places a hold and returns status: "requires_capture" with amount_capturable – no funds move until you capture. Capture the full amount or less; capturing less settles that amount and releases the remainder to the cardholder automatically. A void releases the entire hold. If you never do either, the issuer expires the hold on its own (typically ~7 days) – nothing to clean up on your side, but the funds stay unavailable to the cardholder until then.

Every transition has a webhook: payment.authorized when the hold lands, payment.captured on capture, payment.voided on release.

Incremental authorization (bar tabs, hospitality): raise an open hold before capturing. {id} is the original authorization. amount is the ADDITIONAL cents; the gateway tracks and sends the cumulative total per the Cygma incremental spec. The card must be presented again (card keyed or card_token saved) – holds don’t retain it. Example flow: authorize $10.00 → increment $5.00 (tab $15.00) → increment $10.00 (tab $25.00) → capture $25.00 → tip-adjust to $30.00. Requires the authorization class enabled on the merchant’s terminal profile – contact EPI to enable it.

Tip adjust (restaurant receipt flow): after capturing a sale, add the written tip while the sale is still in the open batch. The tip is itemized to the network (DE54 type 43). After batch close the amount is final – a late tip needs a separate charge.

Void vs refund: void releases a hold or reverses a same-batch charge before settlement. Once a charge has settled, use a refund – a void on a settled transaction returns 409.

The dividing line is settlement. A void works on an authorization or an unsettled sale – it cancels the transaction before it batches, so nothing ever appears on the cardholder’s statement. Once the sale has settled, a void returns 409 already_settled; use a refund instead, which moves money back to the cardholder as its own transaction.

Use a void before settlement (releases a hold / reverses a same-batch sale) and a refund after. A pre-settlement refund is itself processed as a reversal.

A refund is its own object (object: "refund", status: "succeeded") – full, or partial by passing an amount smaller than the charge; you can refund the remainder later. Refunds are gated by the merchant’s channel profile: when the program has refunds disabled, the API returns 403 not_permitted_by_channel even with a valid key and scope. Both moves have webhooks – payment.refunded and payment.voided – so downstream systems hear about reversals they didn’t initiate.

Tokenization turns a card into a reusable card token – a handle for a card on file. Tokenizing needs no amount and no charge: POST /tokens vaults any card outright (the token can be charged or removed later). You can also mint a token as a side effect of a sale by setting save_card on a payment. Charge a saved token by passing card_token to POST /payments, or reference one from a subscription. The raw PAN is never returned – only brand + last4 + expiry.

A card on file always belongs to a customer. POST /tokens, save_card on a payment, and POST /hosted/sessions each require customer_id (an existing customer of the merchant) or customer (created with the card, matched first to an existing customer by email or phone). Without either: 400 customer_required. The card object, and the card.created webhook, carry a customer: { name, email } block. Charging a saved card with card_token needs no customer.

Vaulting a card fires a card.created webhook whichever way you mint it. Deleting a token is a soft revoke – the card stops being chargeable, but history that references it stays intact – and it’s idempotent: deleting an already-deleted token succeeds.

Cards saved at a terminal. save_card: true on a card-present sale (terminal_id) also mints a card token. Each card carries source: online (keyed save_card or POST /tokens) or terminal. A terminal-saved card charges through POST /payments {card_token} only. See Card on file from the reader.

▶ Try the live vault demo – save a card, then charge it repeatedly.

Tokenizing a card without a charge (POST /tokens) is temporarily unavailable in live mode – it returns 503 tokenization_unavailable until the tokenization service is certified. Test mode returns a simulated token, so you can build the full flow today; saving a card via save_card on a live charge also works today.

Hosted fields render the card inputs in a Merchant360-hosted iframe embedded on your page; the card is entered on the Merchant360 origin. The browser exchanges the card for a reusable card_token; you then charge that token server-side with your secret key. Your page handles the token only (SAQ A eligible).

Try the live demo →Runs the real embed in test mode – no key needed.

Two calls make it work:

The response adds customer_id (null in test mode). In live mode, a client token minted without a customer gets 400 customer_required from /hosted/tokenize.

The client token authorizes tokenization only; it cannot charge. It lives 15 minutes by default (expires_in clamps to 60–3600 seconds); if the customer outlasts the session, tokenize() rejects with an expiry error and you mint a new session and re-initialize. Live tokenization is temporarily unavailable and returns 503 until the tokenization service is certified; use a test-mode key (the session inherits the key’s mode and returns a simulated token) to build the full browser flow today. 3-D Secure is not part of this flow (it requires a separate EMV 3DS certification).

A Checkout Session is a fully Cygma-hosted payment page. Create one server-side, then redirect the customer to the returned url. They pay on our page; we charge, mark the session complete, fire checkout.session.completed, and redirect to your success_url. Pass either an amount or a line_items array (their sum becomes the total). Unlike a payment link, a session is single-use and redirect-oriented (success/cancel URLs + a completion webhook).

A session is open until it becomes complete (paid) or expired. Completion is an atomic, single-use claim: exactly one charge can ever complete a session, so a double-submit or a customer paying from two tabs cannot pay twice – and if the charge itself fails, the session reopens so the customer can try again. Expiry (expires_in_minutes, default 24 hours, max 30 days) is evaluated lazily on access, like payment links.

Pass the customer when you have them. An optional customer object – { name, email, phone } – pre-fills the hosted form and powers wallet features: the phone is the buyer’s cell, used as the text-message verification anchor when they save their card with Pay with Vault (absent a phone, the hosted page collects one under the consent box).

Fulfil on the webhook, not the redirect. A customer can pay and close the tab before ever reaching your success_url – the redirect is a courtesy; checkout.session.completed is the truth. Verify the signature, look up the session by id, then ship the order.

Gift cards. When the merchant runs an eGift program, the hosted page also offers “Have a Merchant360 gift card?” – the payer can cover part or all of the session with stored value, and any card surcharge computes on the card portion only. The completed session itemizes it: amount_gift (stored-value portion, 0 when none), amount_charged (total collected = gift + card incl. surcharge), and payment.gift ({ last4, amount, transaction_id }) on the object and the checkout.session.completed webhook. A session fully covered by a gift card completes with no card at all (payment.card.last4 null). Refunding a gift-paid order? Void the redemption with POST /egift/void using payment.gift.transaction_id.

Bank (ACH) and dual pricing. When the merchant offers bank payments (Billing Tools → Settings → Payment methods, with the account’s ACH capability on), the hosted page shows a Card / Bank chooser like the invoice and payment-link pages. A bank payment is not instant: the session moves to status: processing / payment_status: processing the moment the customer submits, the customer is sent to your success_url, and checkout.session.completed fires when the debit settles (a few business days) with payment.method: "bank" – so hold fulfilment on processing and ship on the event, exactly as you would for a card. A returned debit reopens the session (unpaid again). When the merchant runs dual pricing and the session offers an alternative tender (bank, or debit cards priced as cash), the page shows both posted prices and a card pays the card price: amount_charged = amount_total + amount_dual_pricing. That differential is the merchant’s posted card price, not a surcharge – reconcile it as a Card price adjustment, never as “Surcharge” (which is what amount_surcharge is for, and the two never appear together). Bank and dual pricing stay off for test sessions and for sessions minted with metadata.source starting woocommerce until the plugin supports them.

Test-mode keys create is_test sessions: card 4242 4242 4242 4242 approves, 4000 0000 0000 0002 declines, and any test gift card carries a $25.00 balance (ending 0000 = not found) – no money moves. Listen for checkout.session.completed (or poll the session) to fulfil the order.

▶ Try the live demo store – click Buy, pay on the hosted page, land back with the result.

Pay with Vault on your checkout

Every hosted session automatically offers Pay with Vault – the Merchant360 network wallet. A returning customer types the email or mobile number on their wallet, receives a one-time text, and pays with a saved card in seconds; a new customer can save their card at payment with one checkbox. There is no integration work: it appears on the redirect flow, the popup button, WooCommerce, and the Pay Widget – anywhere a session renders.

Two things to know as an integrator: (1) pass customer.phone when you have it – verification codes are delivered by text message; without a phone on the session, the hosted page asks the payer for their cell under the save-my-card box. (2) The wallet lives on the hosted page only – there are no API endpoints to look up, verify, or charge a customer's Vault wallet. Sessions on surcharge programs, open-amount links, gift-covered payments, and test mode skip the wallet.

Checkout Button (popup)

Prefer the customer to stay on your page, PayPal-style? Load m360-checkout.js and the same session opens in a centered popup; when the customer pays, the popup closes and your onComplete fires (closing the popup without paying fires onCancel). Your backend still creates the session with your secret key – the snippet either takes a pre-created url or calls a sessionEndpoint on your server that returns {"url": …}.

<script src="https://cygma.cloud/m360-checkout.js"></script>
<button id="pay-btn">Pay with Merchant360</button>
<script>
  M360Checkout.attach('#pay-btn', {
    sessionEndpoint: '/api/create-checkout-session',   // your backend: POST /v1/checkout/sessions, respond {"url": session.url}
    onComplete: function (r) {
      // UX signal only — confirm via the checkout.session.completed webhook before fulfilling.
      window.location.href = '/thanks';
    },
    onCancel: function () { /* customer closed the popup */ },
  });
</script>

As with the redirect flow, fulfil on the webhook, not the callback – onComplete can be spoofed by a hostile browser; checkout.session.completed cannot.

Inline (embedded iframe)

Want the pay surface embedded on your page rather than a popup or a redirect? Render the session url in an iframe with ?embed=1. The framed page keeps itself sized by posting { type: 'm360:checkout:resize', height } to window.parent, and on success posts { type: 'm360:checkout:complete', nonce, token } to window.parent (no redirect happens inside the frame – your page decides what to do next). Pass a random pnonce and check it echoes back. The card is entered inside this cross-origin frame.

const pnonce = crypto.randomUUID();
const iframe = document.createElement('iframe');
iframe.src = session.url + '&embed=1&pnonce=' + pnonce;   // session.url from POST /v1/checkout/sessions
iframe.style.width = '100%'; iframe.style.border = '0';
document.querySelector('#pay').appendChild(iframe);

const origin = new URL(session.url).origin;
window.addEventListener('message', (e) => {
  if (e.origin !== origin) return;
  if (e.data.type === 'm360:checkout:resize') iframe.style.height = e.data.height + 'px';
  if (e.data.type === 'm360:checkout:complete' && e.data.nonce === pnonce) {
    // UX signal only — confirm via the checkout.session.completed webhook before fulfilling.
    window.location.href = '/thanks';
  }
});

This is the mode the Merchant360 for WooCommerce plugin uses for its inline checkout. Same rule: fulfil on the webhook, not the message.

A payment link is a fixed-amount hosted pay page at merchant360.com/pay/{token} – share the returned url by email, SMS, or embed. For itemized bills use invoices (each has its own hosted URL). For an embeddable, multi-mode checkout (donations, save-a-card, look-up-my-invoice), use the hosted pay widget.

A link is born pending and ends as paid, cancelled, or expired. It becomes paid the moment the customer completes payment on the hosted page – a card payment flips it instantly, a bank (eCheck) payment flips it when the ACH entry settles. payment_link.paid fires on the transition (the event data is the same object GET /payment-links returns); links tied to an invoice also fire invoice.paid. Expiry (expires_in_days) is evaluated lazily: the status flips to expired when the link is next accessed after its deadline, not on a background timer, so an untouched link can read pending past its expiry until someone opens it.

▶ Try the live payment-link demo.

The Pay Widget is a drop-in, embeddable checkout: paste the two-line snippet into any website and it renders a complete, branded payment form in an iframe served from cygma.cloud/{merchantId}. Unlike payment links (single-use URLs) or Checkout Sessions (server-created, cart-shaped), the widget is a permanent fixture on the merchant’s own page – same embed, unlimited payments. If you only want secure card fields inside your own UI, use hosted fields instead.

Everything except the four data- attributes is configured in Merchant360 → Pay Widget – enabled modes, min/max amounts, brand color, receipt addresses, membership programs – and is read server-side on every render, so config changes take effect immediately without touching the embed. The iframe auto-sizes (a cygma:resize postMessage), shows the receipt inline on success, and emails the customer a PDF receipt. The hosted form is protected by Cloudflare Turnstile, a honeypot, and per-IP velocity limits.

Pricing programs. A merchant on a surcharge program sees the itemized credit-card surcharge quoted live from the card number, before paying (debit is never surcharged). A merchant on dual pricing who treats debit cards like cash sees both posted prices – credit price and debit / cash price – and the card number decides which one the button charges. (Dual pricing without that setting does not apply here: the widget’s one-time modes have no bank tender, so there would be no lower price the customer could actually pay.) Subscriptions keep their own card-vs-bank pricing on the plan picker.

Server-to-server: the widget also has a REST endpoint for merchants who collect card details in their own backend – POST https://www.cygma.cloud/api/cygma/v1/charge, authenticated with the widget’s cyg_… bearer key (a separate key from your m360_ API keys: minted, rotated, and revoked on the Pay Widget page, shown once at issuance). It accepts the FIXED_AMOUNT, DONATION, and EXTERNAL_INVOICE modes; invoice-lookup and subscription enrollment are hosted-flow only. Failures return 401 (bad key), 400 (validation), or 402 (processing failure).

How do you know it worked? Widget payments confirm synchronously – the inline receipt (hosted) or the {ok:true} response (API) – and every successful charge also fires payment.succeeded (a full look-up-my-invoice payment additionally fires invoice.paid), so widget activity lands in the same webhook feed as your API charges. Refunds and the fraud ledger live on the Merchant360 → Pay Widget page.

ACH is a delayed-notification payment method: creating a debit or credit tells you the entry was accepted, not that money moved. A successful create returns 201 with status: "queued" and an id (ach_…) – hold on to it. Entries batch to the bank at 4:00 PM ET each banking day; standard entries settle the next banking day. Same-day entries must be queued before noon ET – after that they automatically downgrade to standard. Once submitted, the entry is processing; settlement typically lands in 1–2 banking days, moving it to settled. If the bank rejects it, the entry becomes returned with a return: { code, description } explaining why.

How do you know it worked? You can poll GET /ach/{id}, but we recommend webhooks: subscribe to ach.queued, ach.settled, and ach.returned and you hear about every transition without polling – each payload is the same ach_payment object the GET returns. Treat ach.settled as your “funds are good” signal, not the 201.

A 202 with status: "held" means the entry is under risk review before queueing – id is null at this point. After review it either queues normally or is declined; no action is needed from you.

Returns can arrive well after settlement – a consumer unauthorized return may come up to 60 days after the statement date, so don’t treat settled as unconditionally final on debits. Insufficient-funds returns (R01/R09) are automatically re-presented up to two more times, about 2 banking days apart; the original entry’s resubmitted_as links to the new entry. All other return codes are final.

sec_code is resolved server-side from the account holder type (business → CCD, consumer → PPD/WEB) and returned on the entry – you never set it. Credits are subject to the merchant’s credit policy; both directions obey per-transaction / monthly volume limits. ▶ Try the live demo.

Charging a saved bank? Every successful create returns a bank_account_id (a bank_… token) for the account it used. Pass that back as bank_account_id on a later debit/credit to charge the same account again without re-sending the routing/account – the stored account is used server-side and never re-transmitted. When you pass bank_account_id, the bank_account block is not required.

The create response also includes bank_account_id (the reusable bank_… token for the account charged). A 404 not_found means the bank_account_id isn’t a saved bank on this merchant.

Receipts. A bank debit settles a couple of business days out, so any receipt is emailed on settlement, not at submit. When you charge a saved bank by bank_account_id and the entry isn’t tied to an invoice or payment link, the receipt goes to the receipt_email stored on that saved bank (set it when you create the bank token). If no receipt email is on file, no receipt is sent. Invoice/payment-link debits keep receipting the customer on that document.

A bank token is a reusable handle for a customer bank account on file – the ACH analogue of a card token. Storing a bank moves no money (a $0 prenote validation fires). Charge a saved bank by passing its bank_account_id to POST /ach/debits or /ach/credits, so you never re-send the routing/account. The full account number is encrypted and never returned – only the routing (public ABA) and last 4.

Storing a bank needs the account’s ACH capability to be enabled (like the ACH endpoints) – otherwise POST /banks answers 403 not_enabled. Test-mode keys return a simulated bank_test_…. A charge against a saved bank still obeys the debit-authorization and volume rules of the ACH endpoints.

Offer Affirm and Klarna at checkout. BNPL is a two-step, widget-based flow – the payer authorizes in the provider’s UI, which yields a token you capture into a charge:

1. Create a session – POST /bnpl/sessions for an amount. Klarna returns a client_token for the Klarna SDK; Affirm returns a public_key + script_url for affirm.js (Affirm has no server session).
2. Render the widget on your checkout with that token/key. The payer authorizes and the widget hands you a token – Affirm a checkout_token, Klarna an authorization_token.
3. Capture – POST /bnpl/charges with that token. We authorize + capture at the provider and book the charge. Pass invoice_id to also mark a Merchant360 invoice paid.

Settlement is outside the card rails. Affirm and Klarna deposit directly to the merchant’s bank, so a BNPL charge is its own resource, separate from /payments, and it does not appear in card reporting. A test key uses the provider sandbox; a live key cannot refund a test charge.

For merchants with a PAX card reader (A920 MAX, A920 Pro), POST /payments with a terminal_id sends the sale to the physical device instead of keying a card. This is a semi-integrated flow over this REST API: your software never talks to the reader or to Handpoint, and needs no Handpoint key. The customer taps or inserts on the reader; the card data goes from the reader to the gateway and does not pass through this API or your software. The request and the result use the same payment object as a keyed charge, with channel set to card_present and an id that starts tp_. The same key also takes card-not-present payments, gift cards and billing calls.

What runs on the reader. A reader runs one of two payment apps. Your integration is the same for both:

• Merchant360 Payment App. The reader takes the sale from Merchant360’s queue and runs the Merchant360 flow (tip, the merchant’s pricing program, loyalty, gift). It supports the per-sale terminal_options and entry_mode below and the POS Listener screen.
• Handpoint Payments App. Merchant360 pushes the sale to the reader through Handpoint Cloud (the reader is in Integrated mode). The stock app has no Cancel or Key enter card buttons, so terminal_options have no effect on it; entry_mode: "keyed" opens Handpoint’s manual entry screen.

Gateways. Production readers connect to the Handpoint production gateway and move real money. Developer kits (debug units) connect to the Handpoint staging gateway, which accepts only test (demo) merchants and moves no money. Credentials do not work across the two gateways. See Developer kit.

The call returns 202 with status pending while the customer presents the card. The result arrives as a webhook (payment.succeeded, payment.failed or payment.canceled, whose data is the payment object) or by polling GET /payments/{id} every 2 to 3 seconds. A sale is never cancelled on a timer: one with no final result 360 seconds after it was sent stays pending and is flagged for manual reconciliation. If your request times out before you get the 202, see Recovery.

Earlier endpoints. POST /terminal/charges and GET /terminal/charges/{id} (scope terminal:*, ids are the reader’s result id, statuses approved / declined / cancelled) remain available. Sales sent through them are recorded and fire the same webhooks. The Payment Extension's “Send to card terminal” button uses them.

Send the amount and the reader. Exactly one of card, card_token, card_present or terminal_id is allowed per call. Send an Idempotency-Key (your order id): a retry with the same key returns the original tp_ payment and does not send a second sale to the reader.

Level 2 on card present. Send sales_tax and / or tax_exempt, with the purchase order number in customer_code; the payment echoes sales_tax and tax_exempt. customer_code alone stays reference data. If the gateway rejects the Level 2 data the sale is refused with 502 terminal_error and the gateway’s message, and no payment is created. Level III (line_items, freight) is keyed and card-on-file only.

Test mode. Test keys return tp_test_… ids that resolve on the first GET: succeeded with VISA 4242, or failed when amount is 4100. Any terminal_id is accepted in test mode; use TEST/SIM0001, the simulated reader test keys see on GET /terminal/devices. Self-serve sandbox keys include terminal:read.

Keyed entry on the reader is off by default. It can only be turned on by your POS, per sale, through this API. There is no terminal setting and no terminal-profile (TMS) setting that turns it on, so a person at the reader cannot start a keyed sale that the POS did not ask for.

• terminal_options.allow_keyed: true shows a Key enter card button next to tap / insert. The clerk can still take the card normally.
• entry_mode: "keyed" opens manual card entry directly.
• Both require MOTO enabled for the merchant. Without it the API answers 422 moto_not_enabled and nothing is sent to the reader. MOTO is enabled by EPI on the merchant’s account.
• A keyed sale is a card-not-present transaction for interchange and dispute purposes. entry_method on the result is keyed.

MOTO for the merchant means the terminal profile allows MOTO and Handpoint MOTO is enabled for the merchant. On the Merchant360 Payment App keyed entry runs the app’s MOTO flow for the same amount and the same tp_ payment. On the Handpoint Payments App, entry_mode: "keyed" opens Handpoint’s manual entry screen (moToSale without a card token) and allow_keyed has no button to show. Merchant360 reads keyed results on Handpoint Cloud by result id, because Handpoint’s known issue KI-2026-008 drops the transaction reference on moToSale; nothing changes for your integration.

save_card: true on a card-present sale keeps the card the customer tapped or inserted as a card on file, saved under the customer named by customer_id or customer (one of them is required). When the sale is approved the payment carries card_token (the same field a keyed save_card returns) and card.exp_month / card.exp_year, and card.created fires with source: "terminal" and the customer block. Charge the card later with POST /payments {card_token} and no reader, exactly like a card saved online.

• How it is charged. The reader’s gateway (Handpoint, EPI acquirer) issues the token and keeps the card in its vault. Merchant360 charges it through the same gateway as a card-not-present sale on the merchant’s account. The charge is a tp_ payment with channel: "card_not_present" and entry_mode / entry_method card_on_file; void and refund it like any tp_ payment (Cancel, void, refund).
• Customer. customer_id (an existing customer) or customer (created with the card, matched first by email or phone). Without either: 400 customer_required. Test keys run the same check but write no customer.
• Requirements. MOTO enabled for the merchant (the later charge is card not present) and card saving enabled at the gateway. A reader running the Merchant360 Payment App needs version 2.43.4 or later.
• No tip screen. save_card can’t be combined with tip.prompt (422 tip_with_save_card).
• Card read only. save_card can’t be combined with keyed entry (entry_mode: "keyed" or allow_keyed): 422 keyed_with_save_card.
• If no token comes back. The sale is still a sale: status succeeded with card_token: null.
• Where a terminal-saved card works. POST /payments {card_token}, GET /tokens, GET /tokens/{id} and DELETE /tokens/{id}. It is not accepted by POST /payments/authorize, invoice pay, autopay, subscriptions or /increment (400 invalid_card_token); for those, save the card online (Cards).
• Card data. No card number or security code reaches your software or Merchant360. Merchant360 stores the token, brand, last 4 and expiry month / year.

Test mode. A test save_card sale returns a card_test_… token at once; POST /payments with any card_test_… token approves, and one containing decline declines.

POST /payments/authorize with a terminal_id places a hold on the card the customer taps or inserts. The call works like a card-present sale: 202 with status pending, then payment.authorized (status requires_capture) or payment.failed / payment.canceled. No money moves until you capture. The capture, increment and void calls take the tp_ id and need no card and no reader. This is the same API as the card-not-present Authorize & capture.

• Capture: { amount?, tip_amount? }. amount defaults to the whole hold and cannot exceed it; less is a partial capture and the rest is released. tip_amount is added on top of amount. The payment becomes succeeded with amount = captured + tip; payment.captured fires.
• Increment: { amount } is the ADDITIONAL cents. amount_capturable is the new hold. payment.authorized fires with amount_incremented.
• Void: no body. Releases an open hold, or reverses a captured pre-auth before the batch closes. Full amount only; after the batch closes, refund the capture.
• Expiry: holds expire in 7 to 30 days by issuer. capture_before is the merchant’s terminal-profile pre-auth expiry (default 7 days); after it, capture and increment return 409 authorization_expired.
• Requirements: Pre-auth enabled on the merchant’s terminal profile (its minimum and maximum apply). A reader running the Merchant360 Payment App needs version 2.43.4 or later. Card read only: no entry_mode: "keyed", allow_keyed, save_card or tip.prompt on a hold (400).
• Refund of an uncaptured hold returns 409 requires_capture: capture or void it.

Test mode. Test keys return tp_test_auth_… ids that read as requires_capture on the first GET (failed when amount is 4100); capture, increment and void answer at once.

Before the card is presented: cancel. POST /payments/{id}/cancel (no body) stops the reader and then reads the gateway:

• Not charged: the payment ends canceled with cancel_source: "pos".
• The customer completed it just before the cancel landed: Merchant360 voids it and returns voided with voided_after_cancel: true. A cancelled sale never leaves a charge.
• That automatic void was refused: 409 charged_before_cancel with the payment in the body. Void or refund it yourself.

Cancel on the reader. The Merchant360 Payment App shows a Cancel Sale button while it waits for the card. The merchant’s terminal profile sets the default (“Cancel button on the terminal”, on by default); terminal_options.allow_cancel on the sale overrides it. A clerk cancel ends the payment canceled with cancel_source: "terminal" and fires payment.canceled. On the Handpoint Payments App terminal_options are stored and echoed but have no effect, and a cancel there may come back with cancel_source: null. Once the card is being read the reader cannot stop, and the sale continues to its result. The Handpoint Payments App has its own cancel key that cannot be hidden.

The reader reversed the sale. A reader can reverse an approved sale itself (for example, a chip card pulled out early). The payment ends canceled with cancel_source: "terminal", a cancel_reason_code and a cancel_reason. The card was not charged: do not void, and start a new sale if the customer still wants to pay.

After the sale: void or refund. Neither needs the card.

• POST /payments/{id}/void with no body: full amount, before settlement, within 24 hours. Returns the payment with status voided.
• POST /payments/{id}/void with { amount }: partial void of a card-present sale. One per sale, not on American Express, unsettled, within 24 hours, nothing refunded yet, and partial reversal enabled for the merchant. The payment stays succeeded; amount_voided is the cents reversed and amount what is left. payment.voided fires with partial: true and amount_remaining.
• POST /payments/{id}/refund with { amount? } (omit for the full amount): refunds the card that paid. When the acquirer requires the card, the refund goes to the reader and returns 202 with status pending.
• Both are subject to the merchant’s channel profile (403 not_permitted_by_channel when refunds are off).

A card-present sale takes seconds to minutes and crosses three systems, so plan for a lost response. Merchant360 keeps the authoritative record: it creates the payment before the reader sees the sale, and it resolves the sale on its own (it reads the gateway after the 202, and a background job reconciles against the gateway’s transaction feed). You never have to recover from the reader or Handpoint yourself.

Rules

1. Always send an Idempotency-Key on POST /payments (your order id). If the create times out or the connection drops, resend the identical request with the same key: you get the original tp_ payment back, and no second sale reaches the reader. A different key is a new sale.
2. Store the tp_ id as soon as the 202 arrives.
3. Wait for the result by webhook (payment.succeeded, payment.failed, payment.canceled), by polling GET /payments/{id} every 2 to 3 seconds, or both. Card-present typically resolves in 10 to 30 seconds. A sale is never cancelled on a timer: with no final result 360 seconds after the send it stays pending with requires_review: true, flagged for manual reconciliation. It can still resolve later (the gateway’s transaction feed or the reader’s result), and the webhook fires when it does.
4. requires_review: true: do not start a new sale for that order until the payment resolves; contact EPI support if it stays flagged. Never assume either outcome.
5. Treat only succeeded as paid. failed and canceled mean no charge; you may start a new sale (new idempotency key). Do not start a new sale while the first is still pending: cancel it first.
6. A cancel can resolve to voided. If the customer paid just before your cancel, Merchant360 voids the charge and says so (voided_after_cancel: true).
7. Reconcile daily. GET /transactions?tender=card_present lists every reader sale, including sales run on the device itself; payment_id is the tp_ id. Upsert by id.

Webhook deliveries retry with backoff and can arrive out of order or more than once: process them idempotently by event id and read the payment’s current status. See Webhooks.

tip: { prompt: true } shows the reader’s tip screen with the merchant’s terminal tip settings: its tip percentages (up to 4, none above its maximum tip %), a custom amount, and skip. There is no tip screen when the merchant’s tips are off, set to the printed receipt, or have suggestions off.

The approved amount includes the tip; amount_tip itemizes it and amount_requested is what you sent. In the example, an $18.00 sale with a 15% tip approves for $20.70.

Tip percentages and limits are set on the merchant’s terminal profile by the merchant’s sales office, not per sale. A written tip after a keyed sale uses POST /payments/{id}/tip-adjust, before batch close.

Each reader’s mode is a terminal profile setting (terminalMode), set by the merchant’s sales office in ISO360, by EPI, or by a connected ISV in the ISV portal. The mode decides what the Merchant360 Payment App shows; your API calls are the same in every mode.

What POS Listener shows

• Waiting screen: the merchant’s logo large at the top (the Business Profile logo; else the sales office’s terminal logo; else the Merchant360 logo), the idle message centered (default “Ready for Payment”, up to 40 characters), and the ISV’s logo at the bottom when the merchant is connected to an ISV and the profile shows it.
• Payment screen: a sale from your POS goes straight to card read: the amount, “Tap or insert card”, a Cancel Sale button (unless cancel is off) and a Key enter card button (only when the sale allowed keyed entry). The same payment screen is used in Integrated mode, after the clerk presses Card.
• Staff reach the normal home screen with a 3-second press on the top logo, then the supervisor PIN when one is set. The reader returns to the waiting screen from the back arrow, or after 2 minutes untouched.
• The default idle message shows in the terminal’s language; a custom message shows as typed.

ISV portal. ISVs see their connected merchants and readers in the ISV portal in ISO360: staging and production devices, online status, activation codes, the Merchant360 Payment App settings an ISV may change (mode, the POS Listener settings, receipts, loyalty and display options; pricing, MOTO, tips and security settings stay with EPI), card-present payments, webhook deliveries, and the ISV logo.

Keyed entry is never a profile setting. The Key enter card button appears only when your POS sends terminal_options.allow_keyed: true (or entry_mode: "keyed") on that sale, and only when MOTO is enabled for the merchant. See Keyed entry.

On Handpoint Cloud, Integrated and POS Listener both put the reader in Handpoint’s cloud (integrated) mode. The Handpoint Payments App has no POS Listener screen, logos, or Cancel / Key enter card buttons; those exist only in the Merchant360 Payment App.

Drop the merchant’s full virtual terminal into your product as an iframe: card + Check (ACH), dual pricing, the saved-card vault, receipts – every charge settles on the merchant’s own account. The merchant mints the key in Merchant360 → Billing Tools → Settings → Embedded terminal and registers the domains your product runs on.

<iframe
  src="https://www.merchant360.com/embed/vt?key=vtk_…&header=1"
  style="width:100%;min-height:960px;border:0"
></iframe>

The key bootstraps a 30-minute origin-bound session cookie scoped to /embed; *.example.com domain entries match subdomains. Keys can be revoked at any time. In Handpoint device mode (offered automatically when the merchant has provisioned readers) the cardholder taps/dips on the reader.

Getting the sales back: register a webhook and keep payment.succeeded events whose origin is EMBED_VT / EMBED_HP and whose embed_key_id matches your key – or poll GET /payments with ?origin=EMBED_VT&embed_key=<key id>. Sales keyed anywhere else (the in-app terminal, invoices, pay links) do not match this filter.

GET /terminal/devices lists the merchant’s paired readers. Use terminal_id on POST /payments. available: false with an empty list means the merchant has no card-present provisioning: hide the “send to reader” option.

Readers are boarded, assigned to the merchant, and connected to Merchant360 by the merchant’s sales office, by EPI, or by a connected ISV in the ISV portal (Register a device; Devices, Activation code). Production readers run on the Handpoint production gateway. Staging (debug) readers are registered on the Handpoint staging gateway by Electronic Payments. The Merchant360 Payment App connects with an 8-digit activation code entered on the reader (Settings, Connect to Merchant360); a code is single use. Virtual terminals are never listed. Sandbox (test) keys see one simulated reader.

Check, load, redeem, adjust and move the merchant’s gift-card value with the same m360_ key used for payments. The card must belong to the merchant’s eGift program. Amounts are integer cents. Request fields are camelCase (cardNumber, amountCents); responses are snake_case. The full card number is never returned: responses carry card_last4.

Card input. Single-card routes take cardNumber (12 to 19 digits; spaces and hyphens are stripped) or raw magstripe track1 / track2 from a card reader. Balance, redeem, void and issue take cardNumber only.

Limits. Balance: 30 per key per minute, and 5 per shopper IP per 10 minutes when you forward the shopper’s IP in M360-Client-IP. Loads (activate, add-value, store-credit): 60 per key per minute. History: 30 per key per minute. Idempotency: send an Idempotency-Key (your order id) on every write; a retry with the same key replays the stored response.