Merchant360 API

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

https://www.merchant360.net/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.net/api/m360/v1/openapi.json.

▶ See every tool working live on the examples page.

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.

No merchant yet? Grab a self-serve test key from the sandbox to build against payments, vault, and hosted fields 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.

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).

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

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 three ways: a keyed card, a saved card_token (a card on file – see Cards), or a card-present card_present capture from a terminal or mobile SDK. 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. typenames 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 IndustryIndicatorthe 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.

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.

▶ 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 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-modekey (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).

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.

Customers have no lifecycle to manage – there is no status beyond active, no webhook to wait on, and creates/updates take effect immediately. Archiving a customer hides them from lists; everything referencing them (payments, invoices, subscriptions) stays intact.

Apply a rate to an invoice by passing tax_rate_bps on the invoice (basis points; 625 = 6.25%).

The response includes the customer’s hosted_url (the pay page). ▶ Try the live demo.

An invoice moves DRAFT → OPEN → PARTIAL → PAID; VOID is terminal. Sending it (send: true on create, or POST /invoices/{id}/send) makes it OPEN; from there the customer drives it by paying on the hosted page. Card payments advance the invoice instantly. Bank/eCheck payments advance it only when the underlying ACH entry settles – delayed by 1–2 banking days, like all ACH – so an OPEN invoice with a pending bank payment is normal, not stuck.

How do you know it was paid? Listen for invoice.paid – it fires when the invoice reaches PAID, including when a delayed ACH payment finally settles. invoice.created fires on create. Polling GET /invoices/{id} works too.

Estimates share the invoice shape – same body, same line items, same hosted page – but come back as object: "estimate". The customer reviews and accepts the hosted estimate, which converts it to a normal invoice; from that point it follows the invoice lifecycle (and its webhooks) exactly.

A credit memo credits against an invoice. It comes in three kinds – writeoff, adjustment, chargeback – and applying is a separate step from creating: create a draft and apply it later with POST /credit-memos/{id}/apply, or pass apply: true to do both at once. Applying reduces the invoice balance immediately; voiding a memo reverses its effect.

A payment link is a fixed-amount hosted pay page at merchant360.net/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 fixtureon 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.

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.

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.

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.

For merchants with a paired Handpoint card-present reader, push a sale to the physical terminal instead of keying the card: the customer taps or inserts on the device, EMV data goes straight from the reader to the gateway, and no card data ever crosses this API – you exchange amounts and references only.

The flow is asynchronous, because a human has to present a card: create the charge (returns immediately with status: "pending"), then poll GET /terminal/charges/{id} every 2–3 seconds until it resolves to approved, declined, or cancelled (the customer can cancel on the device). An approved result carries the card brand/last4, the approved amount (tip-inclusive if you enabled the on-reader tip prompt with enable_tip), the auth code, and a transaction_guid for later tip-adjust/void in Merchant360.

Omit terminal_id to use the account's default reader. Send an Idempotency-Key (your order id) so a network retry can't push the sale to the reader twice. Test-mode keys get a simulated reader (TEST/SIM0001) whose charges approve instantly on the first poll. This is the same rail the Payment Extension's “Send to card terminal” button uses.

Recurring billing with trials, discounts, usage-based pricing, and end conditions. The example creates a flat monthly plan; usage-based pricing is set via pricing (below). ▶ Try the live demo.

A subscription is active from the moment you create it. A trial does not get its own status – it’s just an active subscription whose first charge is deferred to trial end. A daily billing cron charges everything due, and each successful charge advances next_charge_at on submit. When a card charge declines, the subscription enters the dunning retry ladder and becomes past_due; a successful retry returns it to active, while exhausting the ladder pauses or cancels it per the merchant’s dunning settings. When an end condition is reached (ends.after occurrences, ends.on date, or ends.at_amount cap), it completes naturally as ended.

subscription.created and subscription.canceled fire on those transitions; each cycle’s charge fires the normal payment webhooks. ACH-billed subscriptions inherit ACH’s delayed settlement – a cycle’s debit is queued on the charge date and settles 1–2 banking days later.

Manage

Appointment status values are the lowercase lifecycle – scheduled → confirmed → in_progress → completed, with canceled and no_show as exits – and you drive every transition yourself via PATCH; nothing advances automatically. Booking a slot the assignee already occupies returns 409 conflict; pass force: true to double-book deliberately.

Capacity-capped group sessions – free RSVPs or paid bookings – shown on the merchant’s public booking page and anywhere the booking widget embeds. A class is the template (title, capacity, pricing); a class session is a dated occurrence; a class bookingis one attendee’s seat. Seats are claimed atomically across API and public bookings.

Payments: API bookings do not collect payment – the public /book page owns card collection (full price or deposit at booking, with Vault quick-pay). Adding an attendee over the API registers them with paid: 0. Public-side require_email / require_phonerules don’t apply to API bookings.

Full sessions: POST /class-sessions/{id}/bookings returns 409 sold_out when no seats remain – pass waitlist: trueto join the waitlist instead. Removing a confirmed attendee promotes the earliest waitlisted person automatically: free classes auto-confirm them (with a “you’re in” email); paid classes email a first-come booking link. Session cancels over the API do not email the roster – cancel from the app to notify attendees.

The merchant’s employee work schedule (Team Schedule) – the same rows the Merchant360 grid and the TableTurn shift schedule edit. A shift belongs to one worker: a login team member (u:<user_id>) or a register PIN (c:<cashier_id>); worker_key: null is an open shift nobody has claimed. New shifts are drafts until published; staff only ever see published shifts.

Download the merchant’s own processing statement as a branded PDF. GET /statements lists the periods a statement exists for (newest first); GET /statements/pdf?year=YYYY&month=MM streams that month’s PDF. The statement is always the merchant behind the key – there’s no cross-merchant access.

Read the merchant’s billing settings that affect the API – accepted methods, ACH direction policy, dual pricing, surcharge program, split-into-payments (installments) config, and business/legal profile. Any valid key can read its own merchant.

Surcharge. surcharge.enabled + surcharge.percent describe a credit-card surcharge program (mutually exclusive with dual_pricing). Use it to display the surcharge to shoppers. Whether a specific card is actually surcharged (credit yes, debit no, and any code-97 drop) is decided by BIN on the hosted pay surface at charge time, so the amount finally charged may differ from a naive amount × percent – reconcile to the charged total, don’t assume it.

Updating settings. PATCH /settings (scope settings:write) changes the two blocks the merchant controls in-app – payments (accepted methods) and installments. It’s a partial merge, so send only what changes. Pricing programs (dual pricing / surcharge), the business profile, and account capabilities are compliance/underwriting-controlled and are not API-writable. Enabling accept_bank_ach requires the account’s ACH capability (else 422).

Custom fields collect extra info at pay time (a PO number, a policy #, a table). Define a field once and it renders on the payer surfaces you enable, plus the staff virtual terminal. Captured values come back as metadata on the payment – and you can also set metadata directly on a charge without defining a field.

Filter GET /payments by a captured value with metadata[<key>]=<value> (for example ?metadata[payment_for]=Golf%20Outing). Several keys combine with AND.

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.

Track accounts-payable vendors, record the payments you make them (check / cash / ACH done elsewhere), and produce 1099-NEC recipient copies at year end. The API records payments and books the P&L expense – it does not disburse money (real ACH payout stays in-app, owner-only).

TIN and bank handling: send a payee’s tax_id and bank_account in plaintext; both are encrypted at rest and only the last-4 is ever returned. Storing a bank does not pay it – real ACH disbursement stays in-app and owner-only.

A payee gets a 1099-NEC when they’re a 1099 vendor and their reportable total for the year is ≥ $600. GET /vendor-payments/1099s?year=YYYY lists who qualifies with a ready flag (and missing listing TIN/address gaps); the recipient-copy PDF is GET /vendor-payments/payees/{id}/1099.

Verify a legal name + TIN (SSN or EIN) against the IRS TIN Match service before 1099 filing. This scope is granted by EPI (it is not available in the self-serve sandbox).

Identical checks are cached for 24 hours: a repeat of the same name + TIN returns the cached verdict, with source reflecting the cache.

Drop the merchant’s full virtual terminalinto 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.net/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.

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.

Merchant360 for Zapierconnects your account to 7,000+ apps with no code: fire a Zap when a payment succeeds, an invoice is paid, a checkout completes, or an estimate is accepted — and create customers, invoices, payment links, and checkout sessions from any other app’s trigger.

Instant triggers(real webhooks, not polling): New Successful Payment, New Refund, New Invoice, Invoice Paid, Checkout Completed, Payment Link Paid, Estimate Accepted — plus a polling New Customer trigger. Actions: Create Customer, Create Invoice (optionally emailed with its hosted pay link), Create Payment Link, Create Checkout Session. Search: Find Customer.

Connect with your Merchant360 API key (sk_live_... or a sandbox sk_test_...— test keys run every Zap against simulated data). Under the hood each Zap registers a scoped endpoint via POST /webhooks and cleans it up when the Zap is turned off — nothing to configure here. The integration is in early access: ask your representative for an invite link while the public Zapier directory listing is in review.

A platform key (m360_isv_…) lets a technology partner (ISV) act on behalf of the merchants in its own book through one integration, instead of collecting a separate key from every merchant.

Example.A POS company with 500 merchants gets ONE key. On each request it adds a header naming which of its merchants the call is for, and it can charge a card, save a card, send an invoice, pull a report, or receive webhooks for that merchant. The key can only reach merchants connected to the partner (by an explicit grant, or by being boarded under the partner’s office), and what it may do on each merchant is bounded by that merchant’s channel profile. Platform keys are issued by EPI or your ISO (not created in the sandbox).

Naming the merchant per request

Every merchant-scoped call (payments, tokens, invoices, …) takes an M360-On-Behalf-Of header naming the target merchant. The key can only reach a merchant it’s connected to – otherwise 403 no_grant. Everything else about the request is identical to a normal merchant key.

Connected accounts

GET /accounts lists every merchant the key can act on. It’s partner-wide, so it takes no M360-On-Behalf-Of header.

Channel guardrails

A partner’s supported feature set is enforced per merchant. If a merchant’s program disables a capability, the API returns 403 not_permitted_by_channel even with a valid key + scope:

Partner webhooks

Register one webhook endpoint with a platform key (no M360-On-Behalf-Of) and it receives events for all your connected merchants. Each delivery’s payload carries a top-level merchant_id so you know which merchant it’s for. Registration, signing, and retries are otherwise identical to merchant webhooks.

curl -X POST https://www.merchant360.net/api/m360/v1/webhooks \
  -H "Authorization: Bearer m360_isv_xxx" \
  -d '{ "url": "https://yourapp.com/hooks/m360", "events": ["payment.succeeded"] }'