--- title: "Update a merchant" method: PATCH path: "/merchants/{username}" tags: ["Merchants"] --- # Update a merchant `PATCH /merchants/{username}` ## Request - Base URL: `https://gateway.pmnts.io/v2/partners` - URL: `https://gateway.pmnts.io/v2/partners/merchants/{username}` - Auth: HTTP basic Updates the merchant's identity/business details. `username`, `status` and `credentials` are read-only here — use the lifecycle endpoints (`/activate`, `/suspend`, `/cancel`) to change `status`, and `/credentials/rotate` to rotate credentials. ## Request body - MerchantUpdateRequest: Any subset of the create business/identity fields. `username`, `status` and `credentials` are read-only — use the lifecycle and credential-rotate endpoints for those. `username` is immutable post-creation. - `name` string - `trading_name` string - `company_number` string - `industry` string - `contact` string - `mcc` string - `website` string - `email` string, email - `accounts_email` string[] - `phone` string - `address` Address - `line1` string, nullable: First line of the street address (e.g. `1 Market St`). - `line2` string, nullable: Second address line (e.g. `Level 4`). - `city` string, nullable: Suburb or city (e.g. `Sydney`). - `state` string, nullable: State or territory (e.g. `NSW`). - `postcode` string, nullable: Postal code (e.g. `2000`). - `country` string, nullable: ISO-3166 alpha-2 country code (e.g. `AU`). - `statement_descriptor` string - `government_controlled` boolean - `country_of_origin` string - `country_code` string - `fee_program_indicator` string - `mastercard_iso_id` string - `visa_iso_id` string - `mastercard_assigned_id` string - `visa_merchant_verification_value` string - `visa_marketplace_identifier` string - `visa_payment_facilitator_indicator` string - `mastercard_payment_facilitator_indicator` string - `bill_payment_provider` boolean - `aggregator_fields_enabled` boolean - `customer_support_phone` string - `card_acceptor_name` string - `card_acceptor_location` string - `card_acceptor_country` string - `timezone` string: IANA timezone identifier. - `merchant_identifier` string: Partner-assigned identifier for the merchant. Distinct from the acquirer-assigned `merchant_id` (MID). ## Response `200` The updated merchant. - Merchant: A merchant under this partner. - `id` string, required: The merchant's username (e.g. `acme-store`). - `status` 'pending' | 'active' | 'suspended' | 'closed', required: The merchant's lifecycle state. - `name` string, nullable: The merchant's legal/registered business name (e.g. `Acme Pty Ltd`). - `trading_name` string, nullable: The name the merchant trades under (e.g. `Acme Store`). - `company_number` string, nullable: The merchant's company/business registration number (e.g. an Australian Business Number, `51824753556`). - `website` string, nullable: The merchant's website URL (e.g. `https://acme.example`). - `mcc` string, nullable: Merchant category code — ISO 18245, 4 digits (e.g. `5411`). - `email` string, email, nullable: Contact email address (e.g. `ops@acme.example`). - `phone` string, nullable: Contact phone number in E.164 format (e.g. `+61730000000`). - `address` Address - `line1` string, nullable: First line of the street address (e.g. `1 Market St`). - `line2` string, nullable: Second address line (e.g. `Level 4`). - `city` string, nullable: Suburb or city (e.g. `Sydney`). - `state` string, nullable: State or territory (e.g. `NSW`). - `postcode` string, nullable: Postal code (e.g. `2000`). - `country` string, nullable: ISO-3166 alpha-2 country code (e.g. `AU`). - `three_d_secure_enabled` boolean: Whether 3-D Secure is enabled for the merchant. - `fraud_screening_enabled` boolean: Whether fraud screening is enabled for the merchant. - `network_tokenisation_enabled` boolean: Whether network tokenisation (Visa VTS / Mastercard MDES) is enabled. - `wallets` string[]: Digital wallets enabled for the merchant. - `surcharging` MerchantSurcharging - `enabled` boolean: Whether card surcharging is enabled for the merchant. - `statement_descriptor` string, nullable: Card-acceptor name shown on the cardholder's statement, max 25 chars (e.g. `ACME STORE`). - `government_controlled` boolean: Whether the merchant is a government-controlled entity. - `country_of_origin` string, nullable: ISO-3166 alpha-2 country of origin (e.g. `AU`). - `country_code` string, nullable: ISO-3166 numeric country code (e.g. `036` for Australia). - `fee_program_indicator` string, nullable: Scheme fee program indicator (e.g. `S`). - `mastercard_iso_id` string, nullable: Mastercard ISO/acquirer identifier (e.g. `00001234`). - `visa_iso_id` string, nullable: Visa ISO/acquirer identifier (e.g. `00005678`). - `mastercard_assigned_id` string, nullable: Mastercard Assigned ID (MAID) (e.g. `MAID12345`). - `visa_merchant_verification_value` string, nullable: Visa Merchant Verification Value (MVV) (e.g. `MVV98765`). - `customer_support_phone` string, nullable: Customer support phone number shown to cardholders (e.g. `+61 7 1234 5678`). - `card_acceptor_name` string, nullable: Card-acceptor name sent to the card schemes (e.g. `ACME STORE`). - `card_acceptor_location` string, nullable: Card-acceptor location/city sent to the card schemes (e.g. `BRISBANE`). - `card_acceptor_country` string, nullable: Card-acceptor country, ISO-3166 alpha-2 (e.g. `AU`). - `timezone` string, nullable: IANA timezone identifier the merchant operates in. - `merchant_identifier` string, nullable: 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` MerchantCredentialsInline: Credentials embedded on the merchant object. `token` is `null` on reads and only populated once by create and credential-rotate. - `username` string, required: The merchant's username (e.g. `acme-store`). - `token` string, nullable, required: The live API token (e.g. `tok_live_3b9c1d…`). `null` except on create / rotate. - `created_at` string, date-time, nullable: When the merchant was created — ISO 8601 UTC (e.g. `2026-05-29T04:21:00Z`). - `updated_at` string, date-time, nullable: When the merchant was last updated — ISO 8601 UTC (e.g. `2026-05-29T04:21:00Z`). ## Other responses - `401`: Missing or invalid HTTP Basic credentials. - `404`: Resource not found. - `422`: The request couldn't be completed. A `validation_error` is something the caller can fix — a bad payload, a merchant that failed validation, or a processor rejecting a field (e.g. the MID); the reason is in `fields`, keyed by a processor-agnostic field name. A `processor_error` is an unactionable upstream failure (a processor was unreachable, busy, or errored); `fields` is empty and the caller should retry or escalate. Raw upstream detail is never surfaced here — only a parsed, processor-neutral reason. --- [API](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api.md) - [All operations](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api/revisions/10f1181ea916?raw)