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. Card 4000 0000 0000 0002 simulates a decline, as does any card_token containing the word decline; any other valid-format card succeeds. Switch to a m360_live_ key to move real money.

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) — so a test id can never be confused with live money.

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 — a network retry can never double-charge. 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.

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.

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 — so a back office can track holds it didn’t place itself.

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.

A card token is a reusable handle for a card on file. Mint one two ways: set save_card on a payment (vaults the card you just charged), or POST /tokens to save a card without charging it. Charge a saved card 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, so the PAN is entered on our origin: it never touches your DOM or your server. The browser exchanges the card for a reusable card_token; you then charge that token server-side with your secret key. This keeps your website and servers out of PCI scope (equivalent to SAQ A) — you handle a token, never card data.

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 can never charge — and it is stateless: nothing is stored server-side, so there is nothing to clean up. 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 simply mint a new session and re-initialize — expired tokens are never renewed in place. 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.

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.

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.

Test-mode keys create is_test sessions: card 4242 4242 4242 4242 approves, 4000 0000 0000 0002 declines — 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.

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.

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.

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

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.

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.

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.

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"] }'