Documentation
DocumentationAPI Reference

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. No webhooks, no 202 Accepted, no provisioning_status or action_required fields, no idempotency-key header. A board that can't complete is reported inline on the POST as a 422 with type: processor_error — 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 (acquirer rejected — 422 processor_error):

{
  "error": {
    "type": "processor_error",
    "message": "NAB rejected the boarding request: invalid MID",
    "fields": { "mid": "must be 10 digits" },
    "request_id": "req_01HZX2…"
  }
}

Fix and re-submit. See Errors and troubleshooting.

What's next