Split Payments

Split payments let you distribute a single payment across multiple parties. This is the foundation for marketplace and platform payment flows where a platform collects a fee and sellers receive their share.

Use Cases

• Marketplaces -- a customer pays once, the platform takes a commission, and one or more sellers receive the remainder
• Gig economy -- split a ride fare between driver payout and platform fee
• Multi-vendor orders -- a single checkout with items from different sellers, each receiving their portion

How Splits Work

1. Create a payment with a split configuration that defines each party's share
2. Confirm and capture the payment normally
3. PerfectPay records each party's allocation
4. Funds are distributed to each party based on the split configuration and payout schedule

Split Payment Flow

Creating a Payment with Splits

Include the split field when creating a payment to define how the amount is distributed.

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": false,
    "return_url": "https://example.com/checkout/complete",
    "metadata": {
      "order_id": "order_5001",
      "marketplace": "true"
    },
    "split": {
      "type": "percentage",
      "data": [
        {
          "recipient_id": "acct_seller_abc",
          "percentage": 85
        },
        {
          "recipient_id": "acct_platform",
          "percentage": 15
        }
      ]
    }
  }'

In this example, the seller receives 85% ($85.00) and the platform collects a 15% fee ($15.00).

Split Types

Fixed Amount Split

{
  "split": {
    "type": "amount",
    "data": [
      { "recipient_id": "acct_seller_abc", "amount": 8500 },
      { "recipient_id": "acct_platform", "amount": 1500 }
    ]
  }
}

The individual amounts must equal the total payment amount.

Platform Fee Collection

The platform account is typically one of the split recipients. Define your platform as a recipient in every split configuration to collect your fee automatically on each transaction.

Split Refunds

When a split payment is refunded, the refund is distributed proportionally across the original split parties. You can also specify custom split amounts for the refund.

Proportional Refund

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": "Partial refund for returned item"
  }'

When no split_refunds field is provided, the refund amount is distributed proportionally based on the original split.

Custom Split Refund

Use the split_refunds field to control exactly how the refund is allocated:

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": "Item returned, platform absorbs fee",
    "split_refunds": [
      { "recipient_id": "acct_seller_abc", "amount": 4250 },
      { "recipient_id": "acct_platform", "amount": 750 }
    ]
  }'

Payout Timing

Each party's split allocation becomes available for payout according to their configured payout schedule. The platform can set different payout cadences for different seller accounts:

• Instant -- funds available immediately via Push-to-Card, RTP, or FedNow (see Instant Settlement)
• Daily -- batched daily payout
• Weekly -- batched weekly payout

Operational Notes

• Split configurations are validated at payment creation -- if the amounts or percentages do not sum correctly, the request is rejected
• Track split allocations in the dashboard under each payment's detail view
• Use Webhooks to receive notifications when payouts to split recipients complete