Boarding a merchant

The core workflow. Three calls in order and you're done.

Steps

1. Find an acquirer you can board onto — GET /acquirers
2. Create the merchant — POST /merchants
3. Board onto one acquirer — POST /merchants/USERNAME/acquirers

Repeat step 3 for each additional acquirer.

Boarding is synchronous. A board that can't complete is reported inline on the POST as a 422 — fix the details and re-submit.

Step 1 — list the acquirers you can board onto

curl https://gateway.pmnts.io/v2/partners/acquirers \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

{
  "items": [
    { "code": "nab", "name": "National Australia Bank" },
    { "code": "cba", "name": "Commonwealth Bank" },
    { "code": "anz", "name": "ANZ" }
  ],
  "next_cursor": null
}

Step 2 — create the merchant

curl -X POST https://gateway.pmnts.io/v2/partners/merchants \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Coffee",
    "username": "acme-coffee",
    "mcc": "5814",
    "trading_country": "AU",
    "settlement_currency": "AUD"
  }'

{
  "username": "acme-coffee",
  "name": "Acme Coffee",
  "status": "active",
  "credentials": {
    "username": "acme-coffee",
    "token": "k_live_…",
    "shared_secret": "…"
  },
  "created_at": "2026-06-16T06:08:46Z"
}

The credentials.token is shown once. Hand it to the merchant immediately — they'll use it against the Gateway API.

Step 3 — board onto an acquirer

curl -X POST https://gateway.pmnts.io/v2/partners/merchants/acme-coffee/acquirers \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acquirer": "nab",
    "mid": "1234567890",
    "tid": "00000001"
  }'

Success (live immediately):

{
  "id": "042-ACQ-NAB",
  "acquirer": "nab",
  "merchant": "acme-coffee",
  "status": "enabled",
  "mid": "1234567890",
  "tid": "00000001",
  "boarded_at": "2026-06-16T06:09:01Z"
}

Failure (a processor rejected the request — 422 processor_error):

{
  "error": {
    "type": "processor_error",
    "message": "a processor is temporarily unavailable",
    "fields": {},
    "request_id": "req_01HZX2…"
  }
}

Fix and re-submit. See Errors and troubleshooting.

Failure, idempotency and retries

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

• Identity create dedupes on (ABN, business name, trading name). Re-posting the same business returns 409 conflict instead of creating a duplicate. A shared ABN alone is allowed.
• Combined create-and-board (a POST /merchants with acquirers) either creates the merchant and every requested connection, or creates nothing. There is no partial state to clean up on the partner's side.
• 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. A processor_error retry is safe for the same reason.

What to do on each failure

See Errors and troubleshooting.

What's next

• Managing acquirer connections — list, update, enable, disable
• Merchant lifecycle — suspend, close, rotate credentials