ISO360 API

Every ISO360 API call is authenticated with a bearer key that belongs to a single agent office. The key carries the office identity, so you never pass an office or agent id in a request – whatever you create lands under the office that owns the key.

• Base URL: https://www.cygma.cloud/api/v1
• Auth: Authorization: Bearer <key> on every request.
• Format: JSON responses; uploads use multipart/form-data.

Generate your key in ISO360 under My Office → ISO360 API. The full secret is shown once at generation – store it somewhere safe; it can’t be retrieved again. Regenerating immediately invalidates the previous key.

• Send it as Authorization: Bearer <key>. Treat it like a password – server-side only, never in client code.
• Each key is scoped (e.g. proposals:create) and rate-limited per minute. Exceeding the limit returns 429.
• Lost or leaked a key? Regenerate it – the old one stops working instantly.

No office yet? Grab a self-serve read-only key from the sandbox and build against demo merchants first.

Request a key at www.cygma.cloud/iso360/sandbox. It is issued instantly and bound to a shared sandbox office (SANDBOX360) that owns three demo merchants, so every read returns a realistic shape without touching a real office’s book.

• Read-only. Granted scopes are merchants:read, applications:read, proposals:read, residuals:read, statements:read, orders:read, reference:read, and webinars:read.
• No writes at all. Boarding, change requests, terminal provisioning, and orders need write scopes EPI grants to a real office. A sandbox key gets 403 on those.
• Capped. Five active keys per email address, and a global daily ceiling. Lost a key? Request another.

1. Create your office key in My Office → ISO360 API.
2. POST a statement PDF (plus the merchant name) to Analyze a statement. The response carries the parsed numbers and a link to the proposal it created under your office.

Uploads a merchant’s prior-processing statement and returns a rate analysis. The call also creates a lead and a draft proposal in the office that owns the key, so the analysis is waiting in ISO360 when your agent logs in.

Request – multipart/form-data:

Pass an Idempotency-Key header to make retries safe: the same key returns the proposal created the first time instead of making a duplicate.

The call is synchronous and can take 15–30 seconds while the statement is read. If the statement can’t be parsed you get a 422 (the draft proposal is still created so the agent can retry in-app).

Build a pricing proposal end-to-end: open a draft (anchored to a merchant or a lead) → save a priced version from pricing knobs → generate the PDF → send it → mark accepted. Writes need proposals:write; reads need proposals:read. The acting user is the key’s creator, and every write reuses the same validation the in-app builder runs – including the office’s pricing limits on a version save.

Endpoints:

• POST /proposals – open a draft (merchant_id or lead_id).
• GET /proposals · GET /proposals/{id} – list / fetch.
• POST /proposals/{id}/versions – save a priced version (knobs.pricing_model required).
• POST /proposals/{id}/pdf – generate the merchant PDF; GET the same path downloads it.
• POST /proposals/{id}/send – email it (to_email) and mark SENT.
• POST /proposals/{id}/accept – mark ACCEPTED.

The response and the PDF carry the merchant-facing pricing figures.

Board a merchant end-to-end. POST /applications (applications:write) opens a draft merchant + application from a structured body – business identity, owners (SSN/DOB/EIN are encrypted at rest), banking, risk, and an optional pricing template – attributed to your office. Target NORTH / OMAHA (Fiserv) or CYGMA.

“Required” below means required for this call to succeed. Fields marked (to submit) are optional at create but must be present before POST /applications/{id}/submit passes – send them now or via PATCH. Run /preflight any time to see exactly what’s still missing.

POST /applications/{id}/preflight tells you exactly what still blocks a submit (the same completeness gate the app enforces), plus the backend’s own requirements – the Fiserv MPA missing[] for NORTH/OMAHA (most of which are completed downstream at File Build), or the MID + 4-digit MCC note for Cygma (which provisions its TID after approval).

POST /applications/{id}/submit executes the signed application and kicks off underwriting (auto due-diligence, GIACT, OFAC, risk scoring). Supply the signer’s name; a 422 returns the reason if the gate isn’t satisfied.

You don’t have to send everything at once – PATCH /applications/{id} fills a DRAFT iteratively (same body, only the fields you send change; owners replaces the list). Set the FinCEN control_question_answered flag here too. Editing is DRAFT-only.

Cygma go-live (MID assignment + TID provisioning) happens on EPI’s side after approval. Owner + bank data must be present before submit.

Submit post-boarding changes on a live merchant. All three use changes:write and follow the same rule: you submit, EPI reviews and commits (maker-checker). The merchant receives an anti-vishing verification code on bank/masterfile submissions.

Bank changes are dual control. One EPI BAC queue person verifies the request and a second, different BAC queue person commits it; the commit is what sends the new account to the processor. The response status is the real one: SUBMITTED, orAWAITING_MERCHANT_CONFIRM for a request the merchant must confirm first. A verified request reads APPROVED until it is committed.

At least one masterfile field is required.

GET /change-requests (+ /{id}, changes:read) tracks any request through review to commit. The response includes the pricing Old→New diff; bank and masterfile fields are omitted.

A paginated, read-only list of boarding applications. Requires the applications:read scope.

Query parameters:

• page – 1-based page number (default 1).
• page_size – items per page, max 100 (default 25).
• status – filter by application status.
• merchant_id – filter to one merchant.

The response envelope (data, page, page_size, total, has_more) is the same across every list endpoint.

Pull a merchant’s Cygma processing statement. Requires the statements:read scope; the merchant must be in the key’s book of business. The list returns available periods (YYYYMM) with a ready-to-fetch pdf_url; the PDF endpoint streams the same branded statement the dashboard renders. 404 when no statement exists for that period.

The active device / SKU catalog that backs order line items. Requires orders:read. Filter with q (manufacturer / model / name) and category. This is reference data – not merchant-scoped.

The rate cards this key’s office can attach to a boarding application – the office’s own templates, its division’s, and the shared EPI library. Requires applications:read. Each row’s scope is office or epi_library. The same id is shown on every template in ISO360 (Pricing Templates) with a copy-to-clipboard API chip, so you can grab it from the dashboard instead of paging this endpoint.

The saved equipment bundles this key’s office can attach to a boarding application (pass the id as equipment_template_id on POST/PATCH /applications). Attaching one materializes a draft order with the template’s lines. Requires applications:read; same office → division → EPI-library scope as pricing templates. The id is also shown on every template in ISO360 (Equipment Templates) with a copy-to-clipboard API chip.

The lookups partners need to set valid values on a boarding application. Requires reference:read. mcc is searchable + paginated; business-types is the fixed tax-classification list.

EPI’s webinar recordings, the same index agents see in ISO360 under Marketing. Requires webinars:read. The list is not merchant-scoped — it is the same catalog for every key.

GET /webinars is paginated and takes four filters, which combine: q (title, presenter, and description), category (a value from /webinars/categories), year (YYYY), and since (YYYY-MM-DD, inclusive). Results are newest first.

embed_url is a youtube-nocookie player URL you can drop straight into an iframe; thumbnail_url is the poster frame. Both are null when youtube_video_id is null. Recordings from 2016–2017 predate the YouTube channel and carry only bankcard_forum_url, a link to the Bankcard Forum thread; there is nothing to embed for those.

Only recordings EPI has published are returned. Videos are served by YouTube, not by this API — these endpoints return the index.

One chargeback with its event timeline and evidence-document list – the detail behind a row from GET /chargebacks. Requires chargebacks:read; the merchant must be in the key’s book.

Per-merchant residual line items for your user, office, and division allocations, by period. Requires residuals:read. Filter with period (YYYYMM) and mid.

Price and place hardware orders. POST /pos-orders/quote (orders:read) computes the money exactly as the in-app order form does – office equipment markup, shipping derived from the SKUs + method, and the active sales-tax rate – without placing anything. POST /pos-orders (orders:write) places a Clover/Exatouch PURCHASE order as an agent using the same math. Look up SKUs from the catalog.

Placing a terminal order requires the ORDER_POS permission on the key’s creator.

Order visibility (all orders:read, scoped to your book):

• GET /pos-orders · GET /pos-orders/{id} – Clover / Exatouch orders.
• GET /terminal-orders · {id} – Terminal Setup Form / terminal orders (file-build → deployment).
• GET /supply-orders · {id} – supplies / paper orders (?kind=PAPER).

Placement SKUs can’t be purchased through the API (they’re provisioned, not sold). Placing terminal-setup and supply/paper orders via the API is a later addition – for now those two are read-only here.

Mint a merchant’s network identity and pull the paperwork. GET /merchants/{id}/terminals (terminals:read) lists devices and their V#/Cygma TID. Minting needs terminals:write.

Idempotent – a merchant that already has a primary TID returns 409 already_provisioned. A non-Cygma-BIN MID returns 422 unsupported_mid; a missing MCC returns 422 needs_mcc. Success also sends the M360 invite.

• POST /terminals/{id}/tsys-vnumber – mint/adopt the TSYS V# for a device. Idempotent. Optional body picks the build: capture_mode TERMINAL (Sierra, default) or HOST (Summit), build_class STAGE / FULL with hwsw (MLTPASS, WEBPASS, HSTPYMT, TSEP, ICT250, ICT220, EQUINOX_AIO), debit, ebt_type + ebt_fns_number, tokenization + token_zone (DEFAULT / LIQUID PAYMENTS) + encryption_vendor (V Voltage / T TDES), auto_close_time (HHMM), commercial_card_capture, partial_auth (2 none / 3 all / 4 card present – sent on every brand range including Mastercard), accept_amex, accept_discover (Amex uses the ESA number on file or the OptBlue SE from the SIC; Discover the number assigned to the MID), merchant_email (MultiPass welcome email), partner_url (TSEP partner website). The service level (RNO / RAO / TAO) is derived and returned with capture_mode and, for Summit, hc_pos_id.
• POST /terminals/{id}/tsys-maintain – one maintenance operation on a live V#, record read back and re-sent with only that change: op block / unblock / merchant_info / hwsw (+ hwsw) / unstage (Stage only → full build, + hwsw) / brand (+ brand AMEX | DISC, enabled) / host_capture (Sierra → Summit, + auto_close_time, commercial_card_capture).
• POST /merchants/{id}/tsys-brands – enable Amex / Discover on the merchant's TSYS front-end record from the numbers on file. Idempotent; optional { amex, discover }.
• GET /terminals/{id}/var-sheet – the branded TSYS VAR sheet as a PDF, regenerated fresh.

Build Merchant360 terminals from a settings template and manage their TMS settings. Settings come in layers, each storing only what it changed: default, linked template, merchant, terminal. A template edit reaches every linked merchant except the settings that merchant or one of its terminals changed. Reads need terminals:read; changes need terminals:write.

• GET /terminal-templates · {id} – the EPI library (Restaurant, Retail, Lite POS, Fuel / Petrol, Services) plus your offices’ templates: id, name, industry, description, library, settings, updated_at.
• GET /merchants/{id}/terminal-settings – template, effective settings, sources (template / merchant / default / derived / handpoint), merchant_only_keys (same on every terminal) and device_keys (can differ per terminal). PINs read "set" or null.
• PATCH /merchants/{id}/terminal-settings – template_id (library or the merchant’s office; null unlinks), replace (template applies in full), settings (key to value; null clears). Handpoint gateway flags and TSYS batch close follow; see notes.
• GET /merchants/{id}/devices – serial, model, nickname, location, is_default, provision_state, activated, last_seen_at, tid_present. Removed devices are left out; ?include_removed=1 lists them too, with removed_at and removed_reason.
• GET · PATCH /merchants/{id}/devices/{serial}/settings – one terminal’s settings and the values it changed (device_keys only; others return 422 not_device_keys).

The V#, TID and API keys are never returned. activation.code signs the Payment App in on the device and is returned once, only when the request issued it (it is also emailed to the merchant). A stopped setup returns 422 with ok: false; send the same serial again to continue. 409 busy while another setup for the merchant is running.

Fix a terminal set up as the wrong model, take a terminal off a merchant, or move it to another merchant. Each call needs terminals:write; a move needs access to both merchants. Responses carry ok, message, steps (each step and how it went) and device. The V#, TID and API keys are never returned. A removed device is not found by these calls (404).

• POST /merchants/{id}/devices/{serial}/change-model: model (one of the seven types). Handpoint has no model change, so the device is released under the old model and set up again under the new one, on the same V#, HC POS ID and app login.
• POST /merchants/{id}/devices/{serial}/remove: mode stock (back in EPI’s Handpoint pool, inventory RETURNED) or out_of_epi (also deleted from EPI’s pool, inventory RETIRED: RMA, sold, lost), optional reason, force. The Payment App is signed out, the V# closed at TSYS and the device kept as history (provision_state REMOVED). When it was the default terminal, the default moves to another working terminal.
• POST /merchants/{id}/devices/{serial}/move: to_merchant_id, optional model, template_id (linked on the new merchant when it has none), force. A V# belongs to the merchant’s TSYS merchant number, so the device is removed here and set up on the new merchant with its own new V#. activation.code is returned once, only when the request issued it, and is also emailed to the new merchant.

Sales on the device not yet in a batch settle on the merchant’s V#: remove and move return 409 unbatched_sales with the count. Close the batch first, or send force: true. A move whose setup on the new merchant stops after the device was removed here returns 422 with ok: false; send POST /merchants/{to_merchant_id}/devices with the serial to finish.

Get pushed the moment something happens instead of polling. Register an endpoint (webhooks:manage) and it receives events for the merchants in your book only. The secret is returned once; verify each delivery with HMAC-SHA256(sha256(secret), rawBody) against X-Webhook-Signature. Failed deliveries retry with backoff (1m → 5m → 30m → 2h → 12h, then give up).

Events: merchant.boarded, merchant.mid_assigned (the processor MID lands at approval - the payload carries the assigned mid), application.submitted, application.approved, application.declined, change_request.updated (a bank / masterfile / pricing change was confirmed, declined, or committed - includes auto_committed when a Plaid-verified bank change processed without manual review), pos_order.created, pos_order.shipped, chargeback.received, invoice.paid, merchant.churn_high, cancellation.requested, merchant.closed, and your office's own tickets: ticket.created, ticket.step_started, ticket.resolved (ticket_id, office_id, merchant, subject, summary, status, priority, due_at, owner and the step) – or "*"for all. Offices can also add endpoints without code from My Office > ISO360 API access > Webhooks.

• GET /webhooks · GET /webhooks/{id} – list / inspect (with recent deliveries).
• DELETE /webhooks/{id} – remove an endpoint.
• POST /webhooks/{id}/test – send a synthetic webhook.test to check your handler.

Resolve a 9-digit ABA routing number to its financial institution. Data comes from the Federal Reserve FedACH Participants Directory, refreshed monthly. Requires the banking:read scope.

Path parameter:

• routing – the 9-digit ABA routing number (non-digits are stripped).

Responses: 422 if the number isn’t 9 digits or fails the ABA Mod-10 checksum; 404 if it passes the checksum but isn’t in the directory (a newer/smaller institution).

Identify a card from its leading digits. Alongside brand, credit / debit / prepaid, issuing bank, country, and the surcharge verdict, the response decodes the full card profile: the card indicator (e.g. H → “Debit hybrid — PIN and signature”), PIN / signature acceptance, the Durbin regulated-issuer flag, and the named debit networks the card routes on (with PINless capability). A credit card that also carries debit networks is flagged dual_routing. The product_id is decoded to a human-readable product tier in product_id_label (e.g. D → “Visa Signature Preferred”). Requires the banking:read scope.

Test data only. This endpoint serves a small static sample set — the well-known test BINs (411111, 555555, 371449, 601100, a debit, a prepaid, and a regulated example) — so you can build and exercise every response shape. It does not serve EPI’s production BIN directory; production lookups are available by agreement with Electronic Payments.

Path parameter:

• bin — the first 6–16 digits of the card number (non-digits are stripped).

Responses: 200 with the card attributes; 422 if the BIN isn’t 6–16 digits; 404 for any BIN outside the sample set (the body lists the available samples).

Successful responses return JSON with the resource under a data key. List endpoints add page, page_size, total, and has_more for pagination. The status code tells you what happened:

The API is versioned in the path (/api/v1). Within a version we only make backward-compatible changes: new fields are always optional, and we never remove or repurpose an existing field. A breaking change ships under a new version, and the old one keeps running through a deprecation window.

Build a tolerant client: ignore response fields you don’t recognize, and don’t depend on field order.