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 /preflightany time to see exactly what’s still missing.

POST /applications/{id}/preflighttells 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}/submitexecutes 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.

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:readscope; 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# (Sierra TID) for a device. Idempotent; no body.
• GET /terminals/{id}/var-sheet – the branded TSYS VAR sheet as a PDF, regenerated fresh.

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 – or "*" for all.

• 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 ReserveFedACH 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.