Merchant Onboarding

This guide walks you through onboarding a new merchant — from creating the entity hierarchy to going live with real payments.

---

Onboarding Lifecycle

Every merchant goes through the following steps before processing live transactions:

1. Create Company — set up the legal entity container
2. Create Merchant under the Company
3. Set up Terminal and Channel — connect the merchant to a payment provider
4. Submit KYB documents — Know Your Business verification at the company level
5. Configure fees and routing — assign fee schedules and routing rules
6. Create API keys for the merchant
7. Merchant integrates using developer documentation
8. Test payment flow in sandbox
9. Request live access — merchant or operator calls POST /merchants/{id}/request-live (sandbox → pending_approval). Requires a FeeSchedule assigned (422 if missing) and Company KYB submitted (if required by tenant feature flag).
10. Operator approves — operator calls POST /merchants/{id}/approve (pending_approval → live). Requires account-management:merchant:approve permission and Company KYB status = approved.

If the request is rejected, the operator calls POST /merchants/{id}/reject (pending_approval → sandbox) with a rejection reason logged. The merchant can address the issues and request live access again.

---

Merchant Statuses

Status transitions are controlled by operators with the appropriate permissions. See the merchant management spec for the full state machine.

---

Prerequisites

• An operator account with merchant management permissions
• Access to the Miracle Portal
• At least one payment provider integration configured at the tenant level

---

Step-by-Step Guides