VidepayDocumentation

Share payouts

Share payouts (payout rules) automatically divide net revenue from every checkout, deposit, subscription charge, and settlement, 70% seller, 20% platform, 10% affiliate, in one atomic on-chain split. Configure steps once per chain; the active rule applies to all incoming payments until deactivated. Revenue sharing without the group chat math fight.

Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.

When should I use this?

Marketplaces splitting revenue between sellers and platform on every sale.
Affiliate or referral commissions deducted at settlement, not via manual transfers.
Treasury allocation without post-payment transfer scripts.

Why use Videpay?

Split happens during settlement, no separate POST /transfer step per payment.
percent, fixed, and remainder step types cover any revenue model.
Only one active rule per chain; makeCurrent activates on create.
Full webhook lifecycle for rule creation, activation, and deactivation.

Marketplace checkout split

A $1,000 USDC checkout auto-routes $700 to the seller wallet, $200 to your platform, and $100 to an affiliate: configured once via POST /payout-rules with stepType percent and remainder, activated with makeCurrent: true.

Before you start

Recipient wallet addresses known at rule creation (recipientAddress per step)
When using fixed steps, set asset (e.g. USDC) so fixed amounts validate correctly
Exactly one remainder step as the final step

How share payouts work

stepType, not type

Request and response bodies use stepType with lowercase values: `percent`, `fixed`, `remainder`. Steps reference recipientAddress (wallet), not recipientId from the transfer registry.

Create a payout rule with ordered steps: percent, fixed, and a final remainder step.
Activate the rule (or pass makeCurrent: true on create). Only one rule is active per chain.
Every settled payment on that chain runs the active rule before crediting merchant balance.
Deactivate the rule to stop splitting; incoming payments then settle entirely to merchant.

Dashboard features

Dashboard → Payments → Share payouts

The dashboard rule builder mirrors POST /payout-rules: name, description, ordered steps with stepType selector, percentage/fixed amount inputs, and Activate / Deactivate actions with step-up auth when enabled.

Create rule: add steps, validate remainder is last, preview split percentages.
Activate: replaces any current active rule on the chain.
Deactivate: stops splitting; historical rule remains for audit.
List view shows status, current flag, and activatedAt timestamp.

Create a payout rule

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`chain`	`string`	No	Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically.
`name`	`string`	Yes	Rule display name (max 120 characters).
`description`	`string`	No	Optional description (max 500 characters).
`asset`	`string`	No	Recommended when using fixed steps (e.g. USDC). Required for sane fixed-amount validation.
`steps`	`array`	Yes	1–15 split steps. Last step must be stepType remainder.
`ruleId`	`uuid`	No	Optional custom rule UUID.
`makeCurrent`	`boolean`	No	When true (default), activate this rule immediately after creation if validation passes.
`authorization`	`object`	No	Dashboard only. Step-up confirmation (PIN, OTP, or 2FA) when a logged-in owner acts in the browser. Omit entirely for secret API key integrations: the server skips this check when you authenticate with x-api-key. On sandbox, any emailed OTP code is `000000` (six zeroes). It's giving dev mode. Live sends a real code.
`authorization.pin`	`string`	No	Transaction PIN when enabled.
`authorization.otpChallengeId`	`uuid`	No	OTP challenge from a prior dashboard auth step. On sandbox, enter `000000` when verifying the emailed code.
`authorization.twoFactorCode`	`string`	No	TOTP code when 2FA is enabled.
`recipientAddress`	`address`	Yes	Wallet that receives this split step at settlement time.
`stepType`	`enum`	Yes	percent, fixed, or remainder. Exactly one remainder step required as the last step.
`percentage`	`decimal string`	No	Required for percent steps (e.g. "70" or "12.5"). Up to 2 decimal places.
`fixedAmount`	`decimal string`	No	Required for fixed steps. Human-readable token amount (e.g. "5" for 5 USDC).

POST/payout-rules

Define split steps. Last step must be stepType remainder. Emits payout-rule.created (and payout-rule.activated when makeCurrent is true).

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03  "chain": "base",04  "name": "Marketplace default split",05  "description": "Seller + platform + affiliate on every checkout",06  "asset": "USDC",07  "makeCurrent": true,08  "steps": [09    {10      "recipientAddress": "0xSellerWallet123456789012345678901234567890",11      "stepType": "percent",12      "percentage": "70"13    },14    {15      "recipientAddress": "0xPlatformWallet123456789012345678901234567890",16      "stepType": "percent",17      "percentage": "20"18    },19    {20      "recipientAddress": "0xAffiliateWallet123456789012345678901234567890",21      "stepType": "remainder"22    }23  ],24  "authorization": {25    "pin": "1234"26  }27}

List, retrieve, activate, and deactivate

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`chain`	`string`	No	Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically.
`includeInactive`	`boolean`	No	Include deactivated rules in list results.
`currentOnly`	`boolean`	No	Return only the active current rule.
`status`	`enum`	No	Filter by active or inactive.
`authorization`	`object`	No	Dashboard only. Step-up confirmation (PIN, OTP, or 2FA) when a logged-in owner acts in the browser. Omit entirely for secret API key integrations: the server skips this check when you authenticate with x-api-key. On sandbox, any emailed OTP code is `000000` (six zeroes). It's giving dev mode. Live sends a real code.
`authorization.pin`	`string`	No	Transaction PIN when enabled.
`authorization.otpChallengeId`	`uuid`	No	OTP challenge from a prior dashboard auth step. On sandbox, enter `000000` when verifying the emailed code.
`authorization.twoFactorCode`	`string`	No	TOTP code when 2FA is enabled.

GET/payout-rules?currentOnly=true&limit=20

List payout rules. Filter by status, includeInactive, or currentOnly for the active rule.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

GET/payout-rules/:prl_9a1b2c3d-4e5f-6789-0abc-def123456789

Retrieve a single rule with full step detail.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

POST/payout-rules/:prl_9a1b2c3d-4e5f-6789-0abc-def123456789/activate

Activate a draft or inactive rule. Deactivates the previous current rule. Emits payout-rule.activated.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "authorization": {03    "pin": "1234"04  }05}

POST/payout-rules/:prl_9a1b2c3d-4e5f-6789-0abc-def123456789/deactivate

Deactivate the current rule. Emits payout-rule.deactivated.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{}

Step types reference

Validation rules

Percent steps must sum to ≤100% before the remainder step. Fixed steps deduct a human-readable amount from gross settlement. The remainder step receives everything left after prior steps: required as the last step.

Field	Type	Required	Description
`recipientAddress`	`address`	Yes	Wallet that receives this split step at settlement time.
`stepType`	`enum`	Yes	percent, fixed, or remainder. Exactly one remainder step required as the last step.
`percentage`	`decimal string`	No	Required for percent steps (e.g. "70" or "12.5"). Up to 2 decimal places.
`fixedAmount`	`decimal string`	No	Required for fixed steps. Human-readable token amount (e.g. "5" for 5 USDC).

Webhooks you'll receive

Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.

Webhookpayout-rule.created

Sent when a payout rule is created.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payout-rule.created04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

Webhookpayout-rule.activated

Sent when a payout rule becomes the active current rule.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payout-rule.activated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

Webhookpayout-rule.deactivated

Sent when an active payout rule is deactivated.

Delivery headers

webhook-headers

01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payout-rule.deactivated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...

← Transfers Programmable payments →