Marketplaces

PerfectPay handles marketplace payment flows where money moves from buyers to sellers through your platform. You collect the payment, split it according to your fee structure, and disburse to sellers on your schedule.

Split Payment Configuration

Split payments let you divide a single payment across multiple recipients at capture time.

POST /payments

curl https://sandbox.perfectpay.ai/payments \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "confirm": true,
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "27",
        "card_cvc": "123",
        "card_holder_name": "Jane Buyer"
      }
    },
    "split_payments": {
      "type": "percentage",
      "splits": [
        { "account_id": "acct_seller_001", "percentage": 85 },
        { "account_id": "acct_platform", "percentage": 15 }
      ]
    },
    "return_url": "https://example.com/order/complete"
  }'

Split types:

• Percentage -- each party gets a share of the total
• Fixed amount -- each party gets a specific amount in minor units

See the split payments guide for advanced splitting patterns.

Seller Onboarding and KYC

Before a seller can receive payouts, they need a merchant account under your platform account.

POST /accounts

curl https://sandbox.perfectpay.ai/accounts \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "Seller Shop",
    "metadata": {
      "platform_seller_id": "seller_001",
      "onboarding_status": "pending_kyc"
    }
  }'

KYC steps depend on your jurisdiction and the connectors you use. Most processors require:

• Legal business name and registration number
• Beneficial owner information
• Bank account details for settlement
• Identity verification documents

Track onboarding status in the account metadata and gate payouts until KYC is complete.

Payout Management

Disburse funds to sellers using the payouts API.

POST /payouts/create

curl https://sandbox.perfectpay.ai/payouts/create \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8500,
    "currency": "USD",
    "payout_type": "bank",
    "customer_id": "cus_seller_001",
    "payout_method_data": {
      "bank": {
        "bank_account_number": "000123456789",
        "bank_routing_number": "110000000",
        "bank_name": "Test Bank",
        "bank_account_holder_name": "Seller Shop LLC"
      }
    }
  }'

Payout Schedules

• Daily -- settle with sellers every business day
• Weekly -- aggregate a week of sales into one payout
• Instant -- push funds immediately using instant settlement rails
• On-demand -- trigger payouts via API when your platform decides

Commission and Fee Handling

Your platform fee is the difference between what the buyer pays and what the sellers receive. Model it in one of two ways:

Percentage-based splits -- define your take rate as a percentage in each split payment. The platform account receives its share automatically.

Fixed platform fee -- deduct a fixed amount from each payment before splitting the remainder to sellers.

Track commissions in the payment metadata for reconciliation:

{
  "metadata": {
    "platform_fee": 1500,
    "platform_fee_currency": "USD",
    "seller_id": "seller_001"
  }
}

Reconciliation and Reporting

For marketplace reconciliation, track these relationships:

• Payment to splits -- which sellers received what portion of each payment
• Splits to payouts -- which accumulated splits funded each payout
• Fees and adjustments -- platform commissions, refund deductions, chargeback recoveries

Use the dashboard or the API to pull transaction history per seller:

curl "https://sandbox.perfectpay.ai/payments/list?customer_id=cus_seller_001&limit=50" \
  -H "api-key: YOUR_SECRET_API_KEY"

Webhook events to subscribe to for marketplace flows:

• payment_succeeded -- buyer payment completed
• payout_succeeded -- seller payout landed
• payout_failed -- payout rejected, needs attention
• dispute_opened -- chargeback filed on a marketplace transaction

See Events & Webhooks for setup.

Refund Handling Across Parties

When a buyer requests a refund on a split payment, decide how to distribute the refund:

• Full refund -- reverse the entire payment and claw back from all parties proportionally
• Partial refund -- refund a specific amount, deducting from the seller portion, the platform portion, or both
• Seller-funded refund -- the platform refunds the buyer and deducts the amount from the seller's next payout

POST /refunds

curl https://sandbox.perfectpay.ai/refunds \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
    "amount": 5000,
    "reason": "requested_by_customer",
    "metadata": {
      "refund_source": "seller",
      "seller_id": "seller_001"
    }
  }'

Next Steps

• Split Payments -- advanced splitting patterns and edge cases
• Payouts -- full payout API reference and rail options
• Connectors -- add processors that support marketplace flows
• Smart Routing -- route marketplace transactions across processors