Creates a merchant. By default (no acquirers in the body) the merchant is identity-only: status is pending, no processing connection is attached, and a fresh API token is generated. The merchant can't take payments until a processing connection is boarded and the merchant is activated. Pass an acquirers array to create and board in one call (see Combined create-and-board below).

The response is 201 with the merchant object and a one-time credentials.token. The token is shown once here and never again on reads — store it.

username may be omitted; one is derived from the trading/business name. Either way the stored username is prefixed with the partner's reseller prefix.

A create is rejected with 409 conflict ("merchant exists") when this partner already has a merchant with the same ABN, business name and trading name — a repeated submit of the same business. A shared ABN alone is allowed: it creates a new merchant.

Combined create-and-board. When the body carries an acquirers array, the merchant is created, every named acquirer is boarded, and the merchant is activated — all in one call. If any acquirer can't be boarded the whole request fails and nothing is created: no merchant, no connections. The failure is reported the same way as the standalone board endpoint:

• 422 validation_error — something the caller can fix: an unsupported currency or card type, a duplicate/missing merchant_id, no processor supports the acquirer for the requested currencies, or a processor rejecting a field (e.g. the MID). fields names the offending field.
• 422 processor_error — an unactionable upstream failure: a processor was unreachable, busy, or rejected the board for a reason the caller can't fix. fields is empty; retry or escalate.
• 404 not_found — an acquirer is unknown or not available to this partner.

Idempotency and retries. Boarding is synchronous and recovery is always the partner re-issuing a call. Safe-retry behaviour is built into the operations themselves:

• Identity create dedupes on the triple (ABN, business name, trading name) — re-posting the same business returns 409 conflict ("merchant exists") instead of producing a duplicate. A shared ABN alone is allowed and creates a new merchant.
• Combined create-and-board either creates the merchant and every requested connection, or creates nothing. On failure the partner re-issues the same request — there is no partial state to clean up.
• Standalone board (POST /merchants/{username}/acquirers) is idempotent per acquirer: re-posting the same acquirer against a merchant that already has it returns the existing connection instead of creating a duplicate. A processor_error retry is safe for the same reason.

What to do on each failure:

• 422 validation_error → read fields, correct the named input (currency, MID, card type, etc.), POST again. Idempotency makes a corrected retry safe.
• 422 processor_error → the request itself is fine; the upstream processor isn't. Back off and re-post the identical request, or escalate if it persists. Don't mutate the payload.
• 409 conflict on create → the merchant already exists for this partner; fetch it with GET /merchants/{username} instead of re-creating.

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

{
  "timezone": "Australia/Sydney"
}