{"openapi":"3.1.0","info":{"title":"Fat Zebra Partner API","version":"1.0.0","summary":"Partner-facing API for boarding and managing sub-merchants and their acquirer connections.","description":"The Partner API lets you (a Fat Zebra partner) create and manage your own\nmerchants, board them onto acquirers, and manage the resulting acquirer\nconnections. You pick an acquirer (your bank relationship); Fat Zebra\ndecides which processors carry it.\n\n## Base URL\n\n```\nhttps://gateway.pmnts.io/v2/partners\n```\n\nAll paths below are relative to that base. Sandbox and staging hosts are in\nthe server list; pick the one for your environment.\n\n## Auth\n\nHTTP Basic. Send your reseller **username** as the Basic username and your\nreseller API **token** as the Basic password\n(`Authorization: Basic <base64(username:token)>`). Every endpoint requires\nit.\n\n## Boarding is synchronous\n\nBoarding a merchant onto an acquirer is synchronous: an acquirer connection\nexists only once it is boarded, so it is always live. A board that can't\ncomplete is reported inline as the POST's `422` error response.\n\n## Envelopes\n\n* **Single resource** — returned as the resource itself, no wrapper.\n* **List** — `{ \"items\": [...], \"next_cursor\": <string|null> }`. A `null`\n  `next_cursor` means the last page; otherwise pass its value as\n  `starting_after` to fetch the next page. List query params are `limit`\n  (default 25, max 100) and `starting_after=<id>`.\n* **Error** — `{ \"error\": { \"type\", \"message\", \"fields\", \"request_id\" } }`.\n  `type` is the coarse class; the specific reason lives in `fields`, keyed by\n  a processor-agnostic field name (e.g. `mid`, `tid`, `currencies`) so you\n  never read a switch's native field paths. `type` values and statuses:\n  `authentication_error` (401), `not_found` (404), `conflict` (409),\n  `validation_error` (422 — something the caller can fix, including a\n  processor rejecting a field like the MID/TID), `processor_error` (422 —\n  an unactionable upstream failure: a processor was unreachable, busy, or\n  rejected us for a reason the caller can't fix; retry or escalate,\n  `fields` is empty).\n\nTimestamps are ISO 8601 UTC. Merchants and partners are addressed by their\n`username`. An acquirer connection's `id` is a derived merchant+acquirer\nvirtual id of the form `<merchant-id>-ACQ-<ACQUIRER-CODE>` (e.g.\n`042-ACQ-NAB`) — not a stored id. Wallets and users carry a stable generated\nid of the form `<owner-id>-<TYPE>-<random>` (e.g. `042-WAL-9f3k2m8q`).\nAcquirers are slug codes (e.g. `nab`, `cba`, `anz`).\n"},"servers":[{"url":"https://gateway.pmnts.io/v2/partners","description":"Production"},{"url":"https://gateway.pmnts-sandbox.io/v2/partners","description":"Sandbox"},{"url":"https://gateway.pmnts-staging.io/v2/partners","description":"Staging"},{"url":"https://gateway.test/v2/partners","description":"Local development"}],"tags":[{"name":"Health","description":"Liveness / auth canary."},{"name":"Partner","description":"The authenticated partner (self)."},{"name":"Merchants","description":"Partner-owned merchant CRUD and lifecycle."},{"name":"Acquirer connections","description":"A merchant's connections to acquirers — board, list, update, enable/disable."},{"name":"Acquirers","description":"The acquirer catalogue this partner may board onto."},{"name":"SSO","description":"Partner SSO enforcement — read state, enforce, disable."},{"name":"Users","description":"Partner dashboard users — CRUD plus deactivate/reactivate."}],"security":[{"PartnerBasicAuth":[]}],"paths":{"/ping":{"get":{"tags":["Health"],"summary":"Auth + partner resolution canary","description":"Smoke-tests auth and partner resolution. Returns `{ \"ok\": true }` on\nsuccess.\n","operationId":"ping","responses":{"200":{"description":"Auth ok; partner resolved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/me":{"get":{"tags":["Partner"],"summary":"Show the authenticated partner (self)","description":"Returns the partner object: id, name, status, environment, branding,\nand defaults.\n","operationId":"showSelf","responses":{"200":{"description":"The authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/me/credentials/rotate":{"post":{"tags":["Partner"],"summary":"Rotate the partner's own API token","description":"Rotates the partner's API `token`. No body is expected. The fresh value\nis returned once — the previous token stops working immediately, so the\ncaller must store the response.\n","operationId":"rotateSelfCredentials","responses":{"200":{"description":"The rotated credentials (returned once).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/users":{"get":{"tags":["Users"],"summary":"List the partner's dashboard users","description":"Returns the partner's dashboard user ids newest-first in the list\nenvelope. Fetch the full user via `GET /users/{id}`.\n","operationId":"listUsers","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"}],"responses":{"200":{"description":"Users list envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Users"],"summary":"Create a dashboard user","description":"Creates a dashboard user under the partner. The `password` is\nwrite-only — it is accepted here but never returned on reads.\n","operationId":"createUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreateRequest"}}}},"responses":{"201":{"description":"The created user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/users/{id}":{"parameters":[{"$ref":"#/components/parameters/UserId"}],"get":{"tags":["Users"],"summary":"Show a user","operationId":"showUser","responses":{"200":{"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Users"],"summary":"Update a user","description":"Updates the user's `name`, `email`, `role` or `password`. The\n`password` is write-only — it is accepted here but never returned.\n","operationId":"updateUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdateRequest"}}}},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}},"delete":{"tags":["Users"],"summary":"Remove a user","description":"Deletes the user. Returns `204` with no content.\n","operationId":"deleteUser","responses":{"204":{"description":"The user was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/users/{id}/deactivate":{"parameters":[{"$ref":"#/components/parameters/UserId"}],"post":{"tags":["Users"],"summary":"Deactivate a user","description":"Locks the account so the user can't sign in. No body is expected.\n","operationId":"deactivateUser","responses":{"200":{"description":"The deactivated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/users/{id}/reactivate":{"parameters":[{"$ref":"#/components/parameters/UserId"}],"post":{"tags":["Users"],"summary":"Reactivate a user","description":"Unlocks the account so the user can sign in again. No body is expected.\n","operationId":"reactivateUser","responses":{"200":{"description":"The reactivated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sso":{"get":{"tags":["SSO"],"summary":"Show SSO enforcement state","description":"Returns whether SSO is enforced for the partner, plus how many users\nare linked to the IdP versus not.\n","operationId":"showSso","responses":{"200":{"description":"The SSO enforcement state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/sso/enforce":{"post":{"tags":["SSO"],"summary":"Enforce SSO","description":"Turns on SSO enforcement for the partner. No body is expected. Returns\n`409 conflict` when active users aren't yet linked to the IdP — they'd\nbe locked out, so link them first.\n","operationId":"enforceSso","responses":{"200":{"description":"The SSO enforcement state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/sso/disable":{"post":{"tags":["SSO"],"summary":"Disable SSO enforcement","description":"Turns off SSO enforcement for the partner. No body is expected.\n","operationId":"disableSso","responses":{"200":{"description":"The SSO enforcement state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/acquirers":{"get":{"tags":["Acquirers"],"summary":"List acquirers this partner may board onto","description":"Scoped to the partner's allowed set (derived from the processors behind\neach acquirer). Returns the list shape; `next_cursor` is always `null`\n(the catalogue is small and unpaginated).\n","operationId":"listAcquirers","responses":{"200":{"description":"Acquirer catalogue list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/acquirers/{code}":{"parameters":[{"$ref":"#/components/parameters/AcquirerCode"}],"get":{"tags":["Acquirers"],"summary":"Show one acquirer's detail","description":"Returns the acquirer's `supported_currencies` and `supported_schemes`.\n\nAn unknown or non-boardable acquirer code returns `404`.\n","operationId":"showAcquirer","responses":{"200":{"description":"Acquirer detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acquirer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/merchants":{"get":{"tags":["Merchants"],"summary":"List the partner's merchants","description":"Returns the partner's merchants newest-first in the list envelope. Each\nitem is a summary (username only) — fetch the full merchant via\n`GET /merchants/{username}`.\n","operationId":"listMerchants","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"}],"responses":{"200":{"description":"Merchants list envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Merchants"],"summary":"Create a merchant","description":"Creates a merchant. By default (no `acquirers` in the body) the merchant\nis identity-only: `status` is `pending`, no processing connection is\nattached, and a fresh API token is generated. The merchant can't take\npayments until a processing connection is boarded and the merchant is\nactivated. Pass an `acquirers` array to create and board in one call\n(see **Combined create-and-board** below).\n\nThe response is `201` with the merchant object and a one-time\n`credentials.token`. The token is shown once here and never again on\nreads — store it.\n\n`username` may be omitted; one is derived from the trading/business\nname. Either way the stored username is prefixed with the partner's\nreseller prefix.\n\nA create is rejected with `409 conflict` (`\"merchant exists\"`) when this\npartner already has a merchant with the same ABN, business name and\ntrading name — a repeated submit of the same business. A shared ABN\nalone is allowed: it creates a new merchant.\n\n**Combined create-and-board.** When the body carries an `acquirers`\narray, the merchant is created, every named acquirer is boarded, and\nthe merchant is activated — all in one call. If any acquirer can't be\nboarded the whole request fails and nothing is created: no merchant,\nno connections. The failure is reported the same way as the standalone\nboard endpoint:\n\n* `422 validation_error` — something the caller can fix: an unsupported\n  currency or card type, a duplicate/missing `merchant_id`, no processor\n  supports the acquirer for the requested currencies, or a processor\n  rejecting a field (e.g. the MID). `fields` names the offending field.\n* `422 processor_error` — an unactionable upstream failure: a processor\n  was unreachable, busy, or rejected the board for a reason the caller\n  can't fix. `fields` is empty; retry or escalate.\n* `404 not_found` — an acquirer is unknown or not available to this\n  partner.\n\n**Idempotency and retries.** Boarding is synchronous and recovery is\nalways the partner re-issuing a call. Safe-retry behaviour is built\ninto the operations themselves:\n\n* **Identity create** dedupes on the triple `(ABN, business name,\n  trading name)` — re-posting the same business returns `409 conflict`\n  (`\"merchant exists\"`) instead of producing a duplicate. A shared\n  ABN alone is allowed and creates a new merchant.\n* **Combined create-and-board** either creates the merchant and every\n  requested connection, or creates nothing. On failure the partner\n  re-issues the same request — there is no partial state to clean up.\n* **Standalone board** (`POST /merchants/{username}/acquirers`) is\n  idempotent per acquirer: re-posting the same `acquirer` against a\n  merchant that already has it returns the existing connection\n  instead of creating a duplicate. A `processor_error` retry is safe\n  for the same reason.\n\n**What to do on each failure**:\n\n* `422 validation_error` → read `fields`, correct the named input\n  (currency, MID, card type, etc.), POST again. Idempotency makes a\n  corrected retry safe.\n* `422 processor_error` → the request itself is fine; the upstream\n  processor isn't. Back off and re-post the identical request, or\n  escalate if it persists. Don't mutate the payload.\n* `409 conflict` on create → the merchant already exists for this\n  partner; fetch it with `GET /merchants/{username}` instead of\n  re-creating.\n","operationId":"createMerchant","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCreateRequest"}}}},"responses":{"201":{"description":"Created merchant, with a one-time token. An identity-only create\n(no `acquirers`) returns a bare `Merchant`. A combined create (with\n`acquirers`) returns a `MerchantOnboardingResult` — a slim payload of\nthe merchant's status, username and token plus a per-acquirer\nboarding status list. A `201` means the merchant and every requested\nacquirer boarded; a boarding failure rolls the whole create back and\nreturns the relevant error below.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Merchant"},{"$ref":"#/components/schemas/MerchantOnboardingResult"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/merchants/{username}":{"parameters":[{"$ref":"#/components/parameters/Username"}],"get":{"tags":["Merchants"],"summary":"Show a merchant","operationId":"showMerchant","responses":{"200":{"description":"The merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Merchants"],"summary":"Update a merchant","description":"Updates the merchant's identity/business details. `username`, `status`\nand `credentials` are read-only here — use the lifecycle endpoints\n(`/activate`, `/suspend`, `/cancel`) to change `status`, and\n`/credentials/rotate` to rotate credentials.\n","operationId":"updateMerchant","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdateRequest"}}}},"responses":{"200":{"description":"The updated merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}},"put":{"tags":["Merchants"],"summary":"Update a merchant (alias for PATCH)","description":"Routes to the same update action as `PATCH /merchants/{username}`; same\nbehaviour and contract.\n","operationId":"replaceMerchant","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdateRequest"}}}},"responses":{"200":{"description":"The updated merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/merchants/{username}/activate":{"parameters":[{"$ref":"#/components/parameters/Username"}],"post":{"tags":["Merchants"],"summary":"Activate a merchant","description":"Transitions the merchant to `active` so it can transact. No body is\nexpected. Activating a merchant that has no active acquirer connection\nis rejected with `409 conflict` (\"merchant has no active processing\nconnection\") — board an acquirer first.\n","operationId":"activateMerchant","responses":{"200":{"description":"The activated merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/merchants/{username}/suspend":{"parameters":[{"$ref":"#/components/parameters/Username"}],"post":{"tags":["Merchants"],"summary":"Suspend a merchant","description":"Transitions the merchant to `suspended`. No body is expected.\n","operationId":"suspendMerchant","responses":{"200":{"description":"The suspended merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/merchants/{username}/cancel":{"parameters":[{"$ref":"#/components/parameters/Username"}],"post":{"tags":["Merchants"],"summary":"Cancel a merchant","description":"Transitions the merchant to `closed`. No body is expected.\n","operationId":"cancelMerchant","responses":{"200":{"description":"The closed merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/merchants/{username}/credentials/rotate":{"parameters":[{"$ref":"#/components/parameters/Username"}],"post":{"tags":["Merchants"],"summary":"Rotate a merchant's credentials","description":"Rotates the merchant's API `token` and its `signing_secret`. No body is\nexpected. The fresh values are returned once — the previous token stops\nworking immediately, so the caller must store the response.\n\nThe response is a bare credentials object: `username`, `token`,\n`signing_secret`, `rotated_at`.\n","operationId":"rotateMerchantCredentials","responses":{"200":{"description":"The rotated credentials (returned once).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/merchants/{username}/acquirers":{"parameters":[{"$ref":"#/components/parameters/Username"}],"get":{"tags":["Acquirer connections"],"summary":"List a merchant's acquirer connections","description":"Returns the merchant's acquirer connections newest-first in the list\nenvelope.\n","operationId":"listAcquirerConnections","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"}],"responses":{"200":{"description":"Acquirer connections list envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnectionListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Acquirer connections"],"summary":"Board a merchant onto an acquirer (synchronous)","description":"Boards the merchant onto an acquirer synchronously and returns the\nresulting connection with `201`. There is no pending state.\n\nYou name an `acquirer` (your bank relationship) and the\nacquirer-assigned `merchant_id` (MID), plus the\n`terminal_id` (TID) when the acquirer needs one. Fat Zebra validates the MID/TID and `currencies`\nagainst its config and boards the merchant onto every processor behind\nthat acquirer that can carry a requested currency — you never name a\nprocessor. Omit `currencies` to board everything the acquirer supports.\n\nBoarding is idempotent: re-posting the same acquirer returns the\nexisting connection rather than creating a duplicate.\n\nFailures are reported inline:\n\n* `422 validation_error` — an unsupported currency, a missing\n  `merchant_id`, or no\n  processor supports the acquirer for the requested currencies. The\n  offending fields are listed under `error.fields`.\n* `422 processor_error` — an underlying processor board was rejected or\n  errored upstream.\n* `404 not_found` — the acquirer is unknown or not available to this\n  partner.\n","operationId":"boardAcquirer","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnectionCreateRequest"}}}},"responses":{"201":{"description":"The boarded connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/merchants/{username}/acquirers/{conn_id}":{"parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/ConnId"}],"get":{"tags":["Acquirer connections"],"summary":"Show an acquirer connection","operationId":"showAcquirerConnection","responses":{"200":{"description":"The acquirer connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Acquirer connections"],"summary":"Update an acquirer connection","description":"Patches the mutable fields only: `priority`, `currencies`,\n`card_types`. Changing `currencies` / `card_types` re-evaluates which\nunderlying processors stay active. `card_types` is narrowed to each\nprocessor's routable set, so a PATCH can't enable a scheme the acquirer\ncan't settle. The `acquirer` and the MID/TID (`merchant_id` /\n`terminal_id`) are immutable once the connection exists.\n","operationId":"updateAcquirerConnection","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnectionUpdateRequest"}}}},"responses":{"200":{"description":"The updated connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/merchants/{username}/acquirers/{conn_id}/enable":{"parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/ConnId"}],"post":{"tags":["Acquirer connections"],"summary":"Enable an acquirer connection","description":"Flips `enabled` to `true` across the underlying links. The routing\ntoggle only — config and MID/TID are untouched. No body is expected.\n","operationId":"enableAcquirerConnection","responses":{"200":{"description":"The enabled connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/merchants/{username}/acquirers/{conn_id}/disable":{"parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/ConnId"}],"post":{"tags":["Acquirer connections"],"summary":"Disable an acquirer connection","description":"Flips `enabled` to `false` across the underlying links — turns a boarded\nconnection off for routing without deleting it. Config and MID/TID are\nuntouched. No body is expected.\n","operationId":"disableAcquirerConnection","responses":{"200":{"description":"The disabled connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"PartnerBasicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic. Send your reseller **username** as the Basic username and\nyour reseller API **token** as the Basic password. Required on every\nendpoint.\n"}},"parameters":{"Limit":{"in":"query","name":"limit","description":"Page size. Defaults to 25, capped at 100.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"StartingAfter":{"in":"query","name":"starting_after","description":"Cursor — the id of the last item from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},"Username":{"in":"path","name":"username","description":"The merchant's username (e.g. `acme-store`).","required":true,"schema":{"type":"string"}},"ConnId":{"in":"path","name":"conn_id","description":"Acquirer-connection id — the derived merchant+acquirer virtual id (e.g. `042-ACQ-NAB`).","required":true,"schema":{"type":"string"}},"UserId":{"in":"path","name":"id","description":"User id (e.g. `123-RU-9f3k2m8q`).","required":true,"schema":{"type":"string"}},"AcquirerCode":{"in":"path","name":"code","description":"Acquirer code (e.g. `nab`).","required":true,"schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"Missing or invalid HTTP Basic credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidToken":{"value":{"error":{"type":"authentication_error","message":"Invalid or missing token","fields":{},"request_id":"req_a1b2c3"}}}}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"value":{"error":{"type":"not_found","message":"Couldn't find merchant","fields":{},"request_id":"req_a1b2c3"}}}}}}},"Conflict":{"description":"The request conflicts with the resource's current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"noActiveConnection":{"value":{"error":{"type":"conflict","message":"merchant has no active processing connection","fields":{},"request_id":"req_a1b2c3"}}}}}}},"ValidationError":{"description":"The request couldn't be completed. A `validation_error` is something the\ncaller can fix — a bad payload, a merchant that failed validation, or a\nprocessor rejecting a field (e.g. the MID); the reason is in `fields`,\nkeyed by a processor-agnostic field name. A `processor_error` is an\nunactionable upstream failure (a processor was unreachable, busy, or\nerrored); `fields` is empty and the caller should retry or escalate.\nRaw upstream detail is never surfaced here — only a parsed,\nprocessor-neutral reason.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"merchantValidation":{"summary":"The merchant details were rejected","value":{"error":{"type":"validation_error","message":"the merchant details were rejected","fields":{"company_name":["can't be blank"],"postcode":["is not a valid postcode"]},"request_id":"req_a1b2c3"}}},"unsupportedCurrency":{"summary":"A currency the acquirer can't carry","value":{"error":{"type":"validation_error","message":"currency not supported by this acquirer","fields":{"currencies":["NZD is not supported by this acquirer"]},"request_id":"req_a1b2c3"}}},"missingConnectionFields":{"summary":"Missing a required connection field","value":{"error":{"type":"validation_error","message":"missing required connection fields: merchant_id, terminal_id","fields":{"merchant_id":["is required"],"terminal_id":["is required"]},"request_id":"req_a1b2c3"}}},"noSupportingProcessor":{"summary":"No processor can carry the acquirer for the requested currencies","value":{"error":{"type":"validation_error","message":"no processor can carry this acquirer for the requested currencies","fields":{"acquirer":["cannot be boarded for the requested currencies"]},"request_id":"req_a1b2c3"}}},"processorRejectedMid":{"summary":"A processor rejected a field (here, the MID) — caller-fixable","value":{"error":{"type":"validation_error","message":"the connection details were rejected","fields":{"mid":["is not supported"]},"request_id":"req_a1b2c3"}}},"processorUnavailable":{"summary":"A processor is busy/errored — not the caller's to fix","value":{"error":{"type":"processor_error","message":"a processor is temporarily unavailable","fields":{},"request_id":"req_a1b2c3"}}}}}}}},"schemas":{"PingResponse":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true,"description":"Always `true` when the API is reachable and the token is valid."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","message","fields","request_id"],"properties":{"type":{"type":"string","description":"Machine-readable error category.","enum":["authentication_error","not_found","conflict","validation_error","processor_error"]},"message":{"type":"string","description":"Human-readable explanation of the error."},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation messages. Empty object when not field-specific."},"request_id":{"type":["string","null"],"description":"Correlation id for this request, for support and tracing (e.g. `req_a1b2c3`)."}}}}},"ListEnvelope":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","description":"The page of results. Each list endpoint overrides the item type."},"next_cursor":{"type":["string","null"],"description":"Id to pass as `starting_after` for the next page; `null` on the last page."}}},"Address":{"type":"object","properties":{"line1":{"type":["string","null"],"description":"First line of the street address (e.g. `1 Market St`)."},"line2":{"type":["string","null"],"description":"Second address line (e.g. `Level 4`)."},"city":{"type":["string","null"],"description":"Suburb or city (e.g. `Sydney`)."},"state":{"type":["string","null"],"description":"State or territory (e.g. `NSW`)."},"postcode":{"type":["string","null"],"description":"Postal code (e.g. `2000`)."},"country":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$","description":"ISO-3166 alpha-2 country code (e.g. `AU`)."}}},"MerchantCredentialsInline":{"type":"object","description":"Credentials embedded on the merchant object. `token` is `null` on reads\nand only populated once by create and credential-rotate.\n","required":["username","token"],"properties":{"username":{"type":"string","description":"The merchant's username (e.g. `acme-store`)."},"token":{"type":["string","null"],"description":"The live API token (e.g. `tok_live_3b9c1d…`). `null` except on create / rotate."}}},"MerchantSurcharging":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether card surcharging is enabled for the merchant."}}},"Merchant":{"type":"object","description":"A merchant under this partner.","required":["id","status"],"properties":{"id":{"type":"string","description":"The merchant's username (e.g. `acme-store`)."},"status":{"type":"string","description":"The merchant's lifecycle state.","enum":["pending","active","suspended","closed"]},"name":{"type":["string","null"],"description":"The merchant's legal/registered business name (e.g. `Acme Pty Ltd`)."},"trading_name":{"type":["string","null"],"description":"The name the merchant trades under (e.g. `Acme Store`)."},"company_number":{"type":["string","null"],"description":"The merchant's company/business registration number (e.g. an Australian Business Number, `51824753556`)."},"website":{"type":["string","null"],"description":"The merchant's website URL (e.g. `https://acme.example`)."},"mcc":{"type":["string","null"],"description":"Merchant category code — ISO 18245, 4 digits (e.g. `5411`)."},"email":{"type":["string","null"],"format":"email","description":"Contact email address (e.g. `ops@acme.example`)."},"phone":{"type":["string","null"],"description":"Contact phone number in E.164 format (e.g. `+61730000000`)."},"address":{"$ref":"#/components/schemas/Address"},"three_d_secure_enabled":{"type":"boolean","description":"Whether 3-D Secure is enabled for the merchant."},"fraud_screening_enabled":{"type":"boolean","description":"Whether fraud screening is enabled for the merchant."},"network_tokenisation_enabled":{"type":"boolean","description":"Whether network tokenisation (Visa VTS / Mastercard MDES) is enabled."},"wallets":{"type":"array","description":"Digital wallets enabled for the merchant.","items":{"type":"string","description":"Wallet type slug (e.g. `apple_pay`, `google_pay`)."}},"surcharging":{"$ref":"#/components/schemas/MerchantSurcharging"},"statement_descriptor":{"type":["string","null"],"description":"Card-acceptor name shown on the cardholder's statement, max 25 chars (e.g. `ACME STORE`)."},"government_controlled":{"type":"boolean","description":"Whether the merchant is a government-controlled entity."},"country_of_origin":{"type":["string","null"],"description":"ISO-3166 alpha-2 country of origin (e.g. `AU`)."},"country_code":{"type":["string","null"],"description":"ISO-3166 numeric country code (e.g. `036` for Australia)."},"fee_program_indicator":{"type":["string","null"],"description":"Scheme fee program indicator (e.g. `S`)."},"mastercard_iso_id":{"type":["string","null"],"description":"Mastercard ISO/acquirer identifier (e.g. `00001234`)."},"visa_iso_id":{"type":["string","null"],"description":"Visa ISO/acquirer identifier (e.g. `00005678`)."},"mastercard_assigned_id":{"type":["string","null"],"description":"Mastercard Assigned ID (MAID) (e.g. `MAID12345`)."},"visa_merchant_verification_value":{"type":["string","null"],"description":"Visa Merchant Verification Value (MVV) (e.g. `MVV98765`)."},"customer_support_phone":{"type":["string","null"],"description":"Customer support phone number shown to cardholders (e.g. `+61 7 1234 5678`)."},"card_acceptor_name":{"type":["string","null"],"description":"Card-acceptor name sent to the card schemes (e.g. `ACME STORE`)."},"card_acceptor_location":{"type":["string","null"],"description":"Card-acceptor location/city sent to the card schemes (e.g. `BRISBANE`)."},"card_acceptor_country":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$","description":"Card-acceptor country, ISO-3166 alpha-2 (e.g. `AU`)."},"timezone":{"type":["string","null"],"description":"IANA timezone identifier the merchant operates in.","examples":["Australia/Sydney","Australia/Brisbane","Australia/Perth","Pacific/Auckland","Europe/London","America/New_York","UTC"]},"merchant_identifier":{"type":["string","null"],"description":"A partner-assigned identifier for the merchant. Distinct from the acquirer-assigned `merchant_id` (MID) — this is a free-form label the partner uses to track the merchant in their own systems."},"credentials":{"$ref":"#/components/schemas/MerchantCredentialsInline"},"created_at":{"type":["string","null"],"format":"date-time","description":"When the merchant was created — ISO 8601 UTC (e.g. `2026-05-29T04:21:00Z`)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the merchant was last updated — ISO 8601 UTC (e.g. `2026-05-29T04:21:00Z`)."}}},"MerchantSummary":{"type":"object","description":"The slim merchant shape returned in list responses — username only.\nFetch the full `Merchant` via `GET /merchants/{username}`.\n","required":["id"],"properties":{"id":{"type":"string","description":"The merchant's username."}}},"MerchantListEnvelope":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MerchantSummary"}}}}]},"MerchantCreateRequest":{"type":"object","description":"Creates a merchant.\n\nRequired to CREATE: `name` and `mcc` only. `mcc` has NO default — the\nmerchant's category is never guessed; omitting it is a\n`422 validation_error`.\n\nTwo modes:\n\n- **Identity-only** (no `acquirers`): creates a `pending` stub with no\n  processing. Board acquirers later via\n  `POST /merchants/{username}/acquirers`. Returns a bare `Merchant`.\n- **Combined create** (with `acquirers`): also boards each listed\n  acquirer and activates the merchant if at least one boards. Boarding\n  is best-effort — failures don't fail the create; each acquirer's\n  outcome is reported in the `MerchantOnboardingResult`. The merchant is\n  `active` when ≥1 acquirer boards, else stays `pending`. Either way the\n  response is `201` with the token revealed once.\n\nReadiness — \"required to create\" is not \"required to transact\". To board\nan acquirer the merchant may need extra business details, depending on\nhow the acquirer is boarded:\n\nThe partner always supplies the acquirer-assigned MID on the\nconnection (TID is optional). Some acquirers also require additional\nbusiness details to board — `company_number`, `trading_name` and\n`address`. Missing fields surface as a `failed` acquirer entry\n(combined create) or a `422` on `POST /merchants/{username}/acquirers`.\n","required":["name","mcc"],"example":{"name":"Acme Pty Ltd","mcc":"5411","trading_name":"Acme Store","company_number":"51824753556","website":"https://acme.example","email":"ops@acme.example","phone":"+61 7 3000 0000","address":{"line1":"1 Market St","line2":"Level 4","city":"Brisbane","state":"QLD","postcode":"4000","country":"AU"},"statement_descriptor":"ACME STORE","government_controlled":false,"country_of_origin":"AU","country_code":"036","fee_program_indicator":"S","mastercard_iso_id":"00001234","visa_iso_id":"00005678","mastercard_assigned_id":"MAID12345","visa_merchant_verification_value":"MVV98765","customer_support_phone":"+61 7 1234 5678","card_acceptor_name":"ACME STORE","card_acceptor_location":"BRISBANE","card_acceptor_country":"AU","acquirers":[{"acquirer":"nab","merchant_id":"MID0012345","terminal_id":"12345678","currencies":["AUD"]}]},"properties":{"name":{"type":"string","description":"Required. The merchant's legal/business name."},"mcc":{"type":"string","pattern":"^\\d{4}$","description":"Required. Merchant category code (ISO 18245, 4 digits). No default —\nomitting or blanking it returns `422 validation_error`.\n","example":"5411"},"trading_name":{"type":"string","description":"Optional at create (defaults to `name`). May be required to board\nsome acquirers.\n"},"company_number":{"type":"string","description":"The merchant's company/business registration number (e.g. an\nAustralian Business Number). Optional at create. May be required to\nboard some acquirers.\n"},"industry":{"type":"string","description":"Optional. Free-text industry descriptor for the merchant."},"contact":{"type":"string","description":"Optional. Primary contact person's name."},"website":{"type":"string","description":"Optional."},"email":{"type":"string","format":"email","description":"Optional."},"accounts_email":{"type":"array","description":"Optional. Accounts/billing email recipients.","items":{"type":"string","format":"email"}},"phone":{"type":"string","description":"Optional."},"address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Business address. Optional at create. May be required to board\nsome acquirers.\n"},"statement_descriptor":{"type":"string","maxLength":25,"description":"Optional. Card-acceptor name. Defaults to the trading/business name, truncated to 25 chars."},"government_controlled":{"type":"boolean","description":"Optional. Whether the merchant is government-controlled. Defaults to false."},"country_of_origin":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Optional. ISO-3166 alpha-2 country of origin."},"country_code":{"type":"string","description":"Optional. ISO-3166 numeric country code."},"fee_program_indicator":{"type":"string","description":"Optional. Scheme fee program indicator."},"mastercard_iso_id":{"type":"string","description":"Optional. Mastercard ISO/acquirer identifier."},"visa_iso_id":{"type":"string","description":"Optional. Visa ISO/acquirer identifier."},"mastercard_assigned_id":{"type":"string","description":"Optional. Mastercard Assigned ID (MAID)."},"visa_merchant_verification_value":{"type":"string","description":"Optional. Visa Merchant Verification Value (MVV)."},"visa_marketplace_identifier":{"type":"string","description":"Optional. Visa Marketplace Identifier (MPI) for marketplace merchants."},"visa_payment_facilitator_indicator":{"type":"string","maxLength":11,"description":"Optional. Visa payment facilitator indicator for scheme rules."},"mastercard_payment_facilitator_indicator":{"type":"string","maxLength":11,"description":"Optional. Mastercard payment facilitator indicator for scheme rules."},"bill_payment_provider":{"type":"boolean","description":"Optional. Whether the merchant is a Bill Payment Service Provider\n(BPSP). Defaults to false.\n"},"aggregator_fields_enabled":{"type":"boolean","description":"Optional. Allow sub-merchant aggregator fields in transaction\nrequests (requires an aggregator agreement with the acquirer).\nDefaults to false.\n"},"customer_support_phone":{"type":"string","description":"Optional. Customer support phone number shown to cardholders."},"card_acceptor_name":{"type":"string","description":"Optional. Card-acceptor name sent to the card schemes. Defaults to\nthe statement descriptor / trading name when omitted.\n"},"card_acceptor_location":{"type":"string","description":"Optional. Card-acceptor location (city) sent to the card schemes."},"card_acceptor_country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Optional. Card-acceptor country, ISO-3166 alpha-2."},"timezone":{"type":"string","description":"Optional. IANA timezone identifier the merchant operates in.\n","examples":["Australia/Sydney","Australia/Brisbane","Australia/Perth","Pacific/Auckland","Europe/London","America/New_York","UTC"]},"merchant_identifier":{"type":"string","description":"Optional. A partner-assigned identifier for the merchant. Distinct\nfrom the acquirer-assigned `merchant_id` (MID) — this is a free-form\nlabel the partner uses to track the merchant in their own systems.\n"},"username":{"type":"string","description":"Optional. When omitted, one is derived from the trading/business\nname. Either way the stored username is prefixed with the partner's\nreseller prefix. Immutable post-creation.\n"},"acquirers":{"type":"array","description":"Optional. When present, boards the merchant onto each acquirer and\nactivates it (combined create). If any acquirer can't be boarded\nthe whole create fails and nothing is created. See the response\n`MerchantOnboardingResult`.\n","items":{"$ref":"#/components/schemas/AcquirerBoardRequest"}}}},"MerchantUpdateRequest":{"type":"object","description":"Any subset of the create business/identity fields. `username`, `status`\nand `credentials` are read-only — use the lifecycle and credential-rotate\nendpoints for those. `username` is immutable post-creation.\n","example":{"trading_name":"Acme Online","website":"https://shop.acme.example","email":"support@acme.example","statement_descriptor":"ACME ONLINE","customer_support_phone":"+61 7 1234 5678","card_acceptor_name":"ACME ONLINE"},"properties":{"name":{"type":"string"},"trading_name":{"type":"string"},"company_number":{"type":"string"},"industry":{"type":"string"},"contact":{"type":"string"},"mcc":{"type":"string","pattern":"^\\d{4}$"},"website":{"type":"string"},"email":{"type":"string","format":"email"},"accounts_email":{"type":"array","items":{"type":"string","format":"email"}},"phone":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"},"statement_descriptor":{"type":"string","maxLength":25},"government_controlled":{"type":"boolean"},"country_of_origin":{"type":"string","pattern":"^[A-Za-z]{2}$"},"country_code":{"type":"string"},"fee_program_indicator":{"type":"string"},"mastercard_iso_id":{"type":"string"},"visa_iso_id":{"type":"string"},"mastercard_assigned_id":{"type":"string"},"visa_merchant_verification_value":{"type":"string"},"visa_marketplace_identifier":{"type":"string"},"visa_payment_facilitator_indicator":{"type":"string","maxLength":11},"mastercard_payment_facilitator_indicator":{"type":"string","maxLength":11},"bill_payment_provider":{"type":"boolean"},"aggregator_fields_enabled":{"type":"boolean"},"customer_support_phone":{"type":"string"},"card_acceptor_name":{"type":"string"},"card_acceptor_location":{"type":"string"},"card_acceptor_country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"timezone":{"type":"string","description":"IANA timezone identifier.","examples":["Australia/Sydney","Australia/Brisbane","Australia/Perth","Pacific/Auckland","Europe/London","America/New_York","UTC"]},"merchant_identifier":{"type":"string","description":"Partner-assigned identifier for the merchant. Distinct from the acquirer-assigned `merchant_id` (MID)."}}},"AcquirerBoardRequest":{"type":"object","description":"One acquirer to board in a combined create — same fields as the body of\n`POST /merchants/{username}/acquirers`.\n","required":["acquirer","merchant_id"],"example":{"acquirer":"nab","merchant_id":"MID0012345","terminal_id":"12345678","currencies":["AUD"]},"properties":{"acquirer":{"type":"string","description":"Acquirer code (e.g. `bnz`). Must be available to the partner."},"merchant_id":{"type":"string","description":"Acquirer-assigned MID. Required."},"terminal_id":{"type":"string","description":"Acquirer-assigned TID. Optional. If you omit it, Fat Zebra generates\na deterministic 8-character placeholder from the merchant's trading\nname (e.g. `ACMEC001`) and uses it across every processor behind\nthis acquirer. The generated value is returned on subsequent reads,\nand once set — supplied or generated — it is immutable.\n"},"currencies":{"type":"array","description":"Optional. Defaults to everything the acquirer supports.","items":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO-4217 currency code (e.g. `AUD`)."}},"card_types":{"type":"array","description":"Optional. Card schemes the connection should accept. Narrowed to\nwhat this acquirer supports — schemes the acquirer can't handle\nare dropped rather than rejected. Omit to accept every scheme the\nacquirer supports.\n","items":{"type":"string","description":"Card scheme (e.g. `VISA`, `MasterCard`)."}},"card_categories":{"type":"array","description":"Optional. Card categories the link handles; overrides the link default.","items":{"type":"string","description":"Card category (e.g. `CREDIT`, `DEBIT`)."}},"merchant_tier":{"type":"string","description":"Optional. Merchant tier; used by the EFTPOS Direct acquirer."},"mpgs_byo_profile":{"type":"boolean","description":"Optional. Marks the MPGS link as bring-your-own profile."}}},"MerchantOnboardingResult":{"type":"object","description":"Returned by a combined create (`POST /merchants` with `acquirers`).\nA slim status payload — the merchant's status, username and one-time\ntoken, plus a per-acquirer boarding status list. When this result is\nreturned every requested acquirer boarded (`status: success`); a\nboarding failure fails the whole create and returns an error instead.\nRead the full merchant via `GET /merchants/{username}` and connections\nvia `GET /merchants/{username}/acquirers`.\n","required":["status","username","acquirers"],"properties":{"status":{"type":"string","enum":["pending","active","suspended","closed"],"description":"`active` — every requested acquirer boarded and the merchant was activated."},"username":{"type":"string","description":"The merchant's username."},"token":{"type":["string","null"],"description":"The one-time API token, revealed once on create."},"acquirers":{"type":"array","description":"Per-acquirer boarding outcome — one entry per requested acquirer, all `success`.","items":{"type":"object","required":["acquirer","status"],"properties":{"acquirer":{"type":"string","description":"The acquirer code from the request (e.g. `nab`)."},"status":{"type":"string","description":"Always `success` on this result — a failure fails the whole create instead.","enum":["success","failed"]},"reason":{"type":"string","description":"Why boarding failed. Not populated on this result."}}}}}},"MerchantCredentials":{"type":"object","description":"Returned once by `POST /merchants/{username}/credentials/rotate`. The\nfull `token` and `signing_secret` are shown here and never again.\n","required":["username","token","signing_secret","rotated_at"],"properties":{"username":{"type":"string","description":"The merchant's username (e.g. `acme-store`)."},"token":{"type":"string","description":"The newly-generated API token (e.g. `tok_live_3b9c1d…`)."},"signing_secret":{"type":"string","description":"The newly-generated signing secret — the merchant's paynow/HMAC secret."},"rotated_at":{"type":"string","format":"date-time","description":"When the credentials were rotated — ISO 8601 UTC (e.g. `2026-06-02T00:00:00Z`)."}}},"AcquirerConnection":{"type":"object","description":"The combined state across every acquirer link provisioned for one\nacquirer. Boarding is synchronous, so a connection that exists is\nalways boarded.\n","required":["acquirer_name","status"],"properties":{"acquirer_name":{"type":["string","null"],"description":"The acquirer's display name (e.g. `NAB`)."},"merchant_id":{"type":["string","null"],"description":"The acquirer-assigned MID (e.g. `ent_a1b2c3d4`)."},"terminal_id":{"type":["string","null"],"description":"The acquirer-assigned TID (e.g. `T0001`), or a Fat Zebra-generated\n8-character placeholder (e.g. `ACMEC001`) if none was supplied at\nboard time. Immutable once set.\n"},"currencies":{"type":"array","description":"Currencies the connection can transact.","items":{"type":"string","description":"ISO-4217 currency code (e.g. `AUD`)."}},"schemes":{"type":"array","description":"Networks the merchant can transact for this acquirer.","items":{"type":"string","description":"Card scheme name (e.g. `Visa`, `Mastercard`)."}},"modes":{"type":"array","description":"Transaction modes the connection supports.","items":{"type":"string","description":"Transaction mode (e.g. `Purchase`, `Auth/Capture`)."}},"wallets":{"type":"array","description":"Wallets the connection accepts.","items":{"type":"string","description":"Wallet type (e.g. `ApplePay`, `GooglePay`, or `ALL`)."}},"three_ds_enabled":{"type":"boolean","description":"Whether a boarded processor for this acquirer supports 3DS."},"status":{"type":"string","enum":["enabled","disabled"],"description":"Routing toggle across the underlying links — disable to turn the connection off without deleting it."}}},"AcquirerConnectionListEnvelope":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AcquirerConnection"}}}}]},"AcquirerConnectionCreateRequest":{"type":"object","required":["acquirer","merchant_id"],"description":"Board onto an acquirer. Name the `acquirer` and send the acquirer-assigned\n`merchant_id` (MID); `terminal_id` (TID) is optional. Fat Zebra validates\nthe MID/TID and `currencies` against its config and boards the merchant\nonto every supporting processor behind the acquirer — you never name a\nprocessor.\n","example":{"acquirer":"nab","merchant_id":"MID0012345","terminal_id":"12345678","currencies":["AUD"]},"properties":{"acquirer":{"type":"string","description":"Required. Acquirer code (e.g. `nab`)."},"merchant_id":{"type":"string","description":"The acquirer-assigned MID. Required."},"terminal_id":{"type":"string","description":"The acquirer-assigned TID. Optional. If omitted, Fat Zebra generates\na deterministic 8-character placeholder from the merchant's trading\nname (e.g. `ACMEC001`) and uses it across every processor behind\nthis acquirer. The generated value is returned on subsequent reads,\nand once set — supplied or generated — it is immutable.\n"},"currencies":{"type":"array","description":"Optional. Defaults to every currency the acquirer supports.","items":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO-4217 currency code (e.g. `AUD`)."}}}},"AcquirerConnectionUpdateRequest":{"type":"object","description":"Only `priority`, `currencies` and `card_types` are mutable. Changing\n`currencies` / `card_types` re-evaluates which underlying processors\nstay active. The `acquirer` and the MID/TID are immutable.\n","example":{"priority":10,"currencies":["AUD","NZD"],"card_types":["visa","mastercard"]},"properties":{"priority":{"type":"integer"},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO-4217 currency code (e.g. `AUD`)."}},"card_types":{"type":"array","description":"Narrowed to the acquirer's routable set; schemes the acquirer can't\nsettle are dropped rather than applied.\n","items":{"type":"string"}}}},"Acquirer":{"type":"object","description":"A catalogue entry describing one acquirer the partner may board onto.\n","required":["code","name"],"properties":{"code":{"type":"string","description":"Acquirer code (e.g. `nab`)."},"name":{"type":"string","description":"The acquirer's display name (e.g. `NAB`)."},"supported_currencies":{"type":"array","description":"Currencies this acquirer can settle.","items":{"type":"string","description":"ISO-4217 currency code (e.g. `AUD`)."}},"supported_schemes":{"type":"array","description":"Card schemes this acquirer supports.","items":{"type":"string","description":"Card scheme name (e.g. `Visa`, `Mastercard`)."}}}},"AcquirerListEnvelope":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Acquirer"}}}}]},"PartnerBranding":{"type":"object","properties":{"display_name":{"type":["string","null"],"description":"Partner brand name shown to merchants (e.g. `Acme Payments`)."},"logo_url":{"type":["string","null"],"description":"Absolute URL of the partner logo (e.g. `https://acme.example/logo.png`)."},"support_email":{"type":["string","null"],"format":"email","description":"Support contact email (e.g. `support@acme.example`)."},"support_phone":{"type":["string","null"],"description":"Support contact phone in E.164 format (e.g. `+61290000000`)."}}},"PartnerDefaults":{"type":"object","properties":{"currencies":{"type":"array","description":"Default currencies for the partner's merchants.","items":{"type":"string","description":"ISO-4217 currency code (e.g. `AUD`)."}},"card_types":{"type":"array","description":"Default accepted card types.","items":{"type":"string","description":"Card type slug (e.g. `visa`, `mastercard`)."}},"timezone":{"type":["string","null"],"description":"IANA timezone identifier.","examples":["Australia/Sydney","Australia/Brisbane","Australia/Perth","Pacific/Auckland","Europe/London","America/New_York","UTC"]}}},"Partner":{"type":"object","description":"The authenticated partner (self). Returned by `GET /me`.\n","required":["id","name","status","environment"],"properties":{"id":{"type":"string","description":"The partner's username (e.g. `acme-partner`)."},"name":{"type":["string","null"],"description":"The partner's display name (e.g. `Acme Payments`)."},"status":{"type":"string","description":"The partner's account status (e.g. `active`)."},"environment":{"type":"string","enum":["live","test"],"description":"`live` in production, `test` elsewhere."},"branding":{"$ref":"#/components/schemas/PartnerBranding"},"defaults":{"$ref":"#/components/schemas/PartnerDefaults"}}},"PartnerCredentials":{"type":"object","description":"Returned once by `POST /me/credentials/rotate`. The full `token` is\nshown here and never again.\n","required":["username","token","rotated_at"],"properties":{"username":{"type":"string","description":"The partner's username (e.g. `acme-partner`)."},"token":{"type":"string","description":"The newly-generated API token (e.g. `sk_live_8f3a…`)."},"rotated_at":{"type":"string","format":"date-time","description":"When the credentials were rotated — ISO 8601 UTC (e.g. `2026-06-02T00:00:00Z`)."}}},"SsoState":{"type":"object","description":"The partner's SSO enforcement state and IdP-link counts.\n","required":["enforced","users_total","users_linked","users_unlinked"],"properties":{"enforced":{"type":"boolean","description":"Whether SSO is enforced for the partner."},"users_total":{"type":"integer","description":"Total active users."},"users_linked":{"type":"integer","description":"Active users linked to the IdP."},"users_unlinked":{"type":"integer","description":"Active users not yet linked to the IdP."}}},"User":{"type":"object","description":"A partner dashboard user.","required":["id","name","email","role","status"],"properties":{"id":{"type":"string","description":"User id (e.g. `123-RU-9f3k2m8q`)."},"name":{"type":"string","description":"The user's full name (e.g. `Jane Smith`)."},"email":{"type":"string","format":"email","description":"The user's email address (e.g. `jane@acme.example`)."},"role":{"type":"string","description":"The user's access level.","enum":["admin","member"]},"status":{"type":"string","description":"The user's account status.","enum":["active","locked","reset_requested"]},"mfa_enabled":{"type":"boolean","description":"Whether multi-factor authentication is enabled for the user."},"sso_linked":{"type":"boolean","description":"Whether the user is linked to the partner's IdP."},"last_login_at":{"type":["string","null"],"format":"date-time","description":"When the user last logged in — ISO 8601 UTC (e.g. `2026-06-01T09:30:00Z`). `null` if never."},"created_at":{"type":["string","null"],"format":"date-time","description":"When the user was created — ISO 8601 UTC (e.g. `2026-05-01T00:00:00Z`)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the user was last updated — ISO 8601 UTC (e.g. `2026-05-15T00:00:00Z`)."}}},"UserSummary":{"type":"object","description":"The slim user shape returned in list responses — id only. Fetch the\nfull `User` via `GET /users/{id}`.\n","required":["id"],"properties":{"id":{"type":"string","description":"The user's id (e.g. `123-RU-9f3k2m8q`)."}}},"UserListEnvelope":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserSummary"}}}}]},"UserCreateRequest":{"type":"object","required":["name","email","password"],"example":{"email":"dana@partner.example","password":"S3curePassw0rd!","name":"Dana Ops","role":"admin"},"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","writeOnly":true,"description":"Accepted on write only; never returned on reads."},"role":{"type":"string","enum":["admin","member"],"default":"member"}}},"UserUpdateRequest":{"type":"object","description":"Any subset of the user's `name`, `email`, `role` or `password`. The\n`password` is write-only.\n","example":{"name":"Dana Operations","role":"member"},"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","writeOnly":true,"description":"Accepted on write only; never returned on reads."},"role":{"type":"string","enum":["admin","member"]}}}}}}