Managed Merchant Onboarding to First Payment

Persona: Marketplace operator, platform-as-a-service, franchise management system, accounting software with multi-entity support.

Scenario: Your platform needs to onboard a new sub-merchant (e.g. a business signing up to your product), submit their identity and compliance documents to Pinch, wait for approval, and then collect payments on their behalf using a single set of master API credentials.

📘

Before building this flow, make sure Managed Merchants are enabled on your master account. Contact [email protected] if you're unsure.

Endpoint sequence

1. POST /merchants/managed: create the sub-merchant account
2. POST /merchants/upload-document: submit compliance documents (one file per call)
3. compliance-updated webhook event: wait for approval
4. POST /webhooks: set up event delivery for the sub-merchant
5. POST /payers + POST /payments: collect payments on behalf of the sub-merchant

All calls from step 2 onwards use the Current-Merchant: mch_XXXXXXXX header to act on behalf of the sub-merchant.

Step 1: Create the sub-merchant

Use your master merchant API credentials (no Current-Merchant header required here):

POST https://api.getpinch.com.au/test/merchants/managed
Authorization: ******
pinch-version: 2020.1
Content-Type: application/json

{
  "companyName": "Acme Pty Ltd",
  "contactFirstName": "John",
  "contactLastName": "Smith",
  "contactEmail": "[email protected]",
  "contactPhone": "0400000000",
  "abn": "12345678901"
}

Save the id from the response (mch_XXXXXXXX). This is the sub-merchant's Merchant ID and is required for all subsequent calls on their behalf.

Step 2: Submit compliance documents

Pinch must verify the sub-merchant's identity before they can take live payments. Upload their documents using POST /merchants/upload-document with the Current-Merchant header set to their Merchant ID.

Upload is one file per request. You will typically need multiple calls.

# Identity document (driver's licence front)
curl -X POST https://api.getpinch.com.au/test/merchants/upload-document \
  -H "Authorization: ******" \
  -H "Current-Merchant: mch_XXXXXXXX" \
  -H "pinch-version: 2020.1" \
  -F "documentType=identity-document" \
  -F "file=@/path/to/drivers-licence-front.pdf"

# Identity document (driver's licence back)
curl -X POST https://api.getpinch.com.au/test/merchants/upload-document \
  -H "Authorization: ******" \
  -H "Current-Merchant: mch_XXXXXXXX" \
  -H "pinch-version: 2020.1" \
  -F "documentType=identity-document" \
  -F "file=@/path/to/drivers-licence-back.pdf"

# Financial document (bank statement)
curl -X POST https://api.getpinch.com.au/test/merchants/upload-document \
  -H "Authorization: ******" \
  -H "Current-Merchant: mch_XXXXXXXX" \
  -H "pinch-version: 2020.1" \
  -F "documentType=financial-document" \
  -F "file=@/path/to/bank-statement.pdf"

# Business registration (ASIC extract or ABN registration)
curl -X POST https://api.getpinch.com.au/test/merchants/upload-document \
  -H "Authorization: ******" \
  -H "Current-Merchant: mch_XXXXXXXX" \
  -H "pinch-version: 2020.1" \
  -F "documentType=business-registration" \
  -F "file=@/path/to/asic-extract.pdf"

See the Compliance Guide for the full list of accepted document types, file requirements, and details on UBOs and trust structures.

Step 3: Wait for compliance approval

Compliance review is a human-in-the-loop process at Pinch. Subscribe to the compliance-updated webhook event. Pinch will POST to your endpoint when the review is complete.

{
  "Type": "compliance-updated",
  "Data": {
    "ComplianceSubmission": {
      "SubmissionStatus": "approved",
      "MerchantStatus": "active"
    }
  }
}

Once MerchantStatus is active, the sub-merchant can take live payments.

If the status is rejected, surface a clear message to the sub-merchant and provide a path to upload corrected documents.

Step 4: Set up a webhook for the sub-merchant

Before collecting payments, subscribe to the sub-merchant's payment events using the Current-Merchant header:

POST https://api.getpinch.com.au/test/webhooks
Authorization: ******
Current-Merchant: mch_XXXXXXXX
pinch-version: 2020.1
Content-Type: application/json

{
  "url": "https://yourplatform.com/webhooks/pinch",
  "eventTypes": ["bank-results", "realtime-payment", "transfer"],
  "format": "camelCase"
}

Step 5: Collect payments on behalf of the sub-merchant

All payment API calls use your master merchant credentials with the Current-Merchant header. Create a payer and a payment as you would normally:

POST https://api.getpinch.com.au/test/payers
Authorization: ******
Current-Merchant: mch_XXXXXXXX
pinch-version: 2020.1
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]"
}

POST https://api.getpinch.com.au/test/payments
Authorization: ******
Current-Merchant: mch_XXXXXXXX
pinch-version: 2020.1
Content-Type: application/json

{
  "payerId": "pyr_XXXXXXXX",
  "sourceId": "src_XXXXXXXX",
  "amount": 15000,
  "description": "Invoice #001",
  "transactionDate": "2026-08-01"
}

Key caveats

• Current-Merchant is required for all sub-merchant operations. Every API call you make on behalf of a sub-merchant (payers, payments, sources, webhooks, documents) must include Current-Merchant: mch_XXXXXXXX. Without it, the call is attributed to your master account.
• Do not take live payments until MerchantStatus: "active". A sub-merchant account created via API is in an unverified state until compliance is approved.
• Document uploads are one file per request. Plan your upload flow to loop through each required document.
• Files must be less than 20MB and uploaded as multipart/form-data.
• Compliance review is not instant. Build your onboarding UI to clearly communicate that approval is pending and to surface a prompt if documents are rejected.

What to do next

• Managed Merchants Guide: conceptual overview of the Managed Merchants model
• Compliance Guide: full document requirements
• Vault a Payment Source: collecting and storing payment details from a sub-merchant's customers
• Webhooks: setting up and securing webhook endpoints