Change a beneficiary

Changing where a seller's money goes is the workflow most worth attacking, so it is the one the platform makes slowest. The request waits out a window, both the old and the new verified channel are told, and a second person approves with a fresh second factor.

1. →
2. →
3. →
4. →
5. →
6. →
7. →
8. →
9. →

Click any step to read what happens there and what can refuse it.

The API calls

# 1. the seller
curl -X POST "$API/v1/sellers" -H "x-api-key: $KEY" -H "x-pehmen-organization: $ORG" \
  -H "x-pehmen-environment: test" -H "idempotency-key: $(uuidgen)" -H "content-type: application/json" \
  -d '{"merchant_seller_ref":"atlas-events"}'

# 2. the new destination (202: a worker registers it)
curl -X POST "$API/v1/beneficiaries" ... \
  -d '{"seller_id":"slr_…","details":{"account_number":"0012345678","bank_code":"DBSSSGSGXXX","country_code":"SG","currency":"SGD","account_name":"Atlas Event Co Pte Ltd"}}'

# 3. the request
curl -X POST "$API/v1/beneficiary-changes" ... \
  -d '{"seller_id":"slr_…","new_beneficiary_id":"bnf_…"}'

Adding and verifying a channel needs a dashboard session with a fresh second factor; it cannot be done with an API key.

What the approver should read before approving

On the change page: the From and To destinations (masked account, token, name match and its method), the cooling-off state (must read elapsed), the out-of-band notification rows (both SENT), and the Gate decision with its reason codes. A change with no notification recorded is itself worth asking about before approving.

What refuses

Refusal	Why
validation_failed: seller has no verified notification channel	Register and verify a channel first.
ato_session_blocked (403)	The requester or approver changed credentials in the last 24 hours.
cooling_off_active (409)	The window has not elapsed, or a notice is still undelivered.
approver_must_differ	The requester tried to approve.
step_up_required	The approver's second factor is older than five minutes.
beneficiary_fingerprint_conflict	The same account is already registered for this workspace.