Merchant lifecycle

Once a merchant exists, you have a handful of lifecycle actions beyond create. See Boarding a merchant for create.

Read and list

# List all your merchants (paginated — see Conventions)
curl https://gateway.pmnts.io/v2/partners/merchants \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

# Read one
curl https://gateway.pmnts.io/v2/partners/merchants/acme-coffee \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

Update

Prefer PATCH for partial updates. PUT is a full replace and rarely needed.

curl -X PATCH https://gateway.pmnts.io/v2/partners/merchants/acme-coffee \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "trading_name": "Acme Coffee Co." }'

Activate / suspend / cancel

Action	Reversible?	When to use
`POST /merchants/USERNAME/suspend`	Yes — call `/activate` or `/cancel`	Risk flag, billing issue, temporary pause
`POST /merchants/USERNAME/activate`	n/a	Bring a suspended or cancelled merchant back online
`POST /merchants/USERNAME/cancel`	Yes — call `/activate` or `/suspend`	Merchant off-boarded, with access to historical transactional data

curl -X POST https://gateway.pmnts.io/v2/partners/merchants/acme-coffee/suspend \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "billing arrears" }'

curl -X POST https://gateway.pmnts.io/v2/partners/merchants/acme-coffee/cancel \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "off boarding" }'

Rotate credentials

If the merchant's gateway token might be compromised:

curl -X POST https://gateway.pmnts.io/v2/partners/merchants/acme-coffee/credentials/rotate \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

The new token is in the response — shown once, like at create time. See Authentication.