<!-- x-generated: Generated by the Hyperscale artifact pipeline; do not edit by hand -->

# Creator Payouts & Tax Docs

> The frozen Creator Payouts & Tax Docs Product Build, version 1.

- Composition id: `creator_payouts_tax_docs`
- Version: 1
- Digest: `3cb99c74dc26e6c016b6db4442e7e7d538db0d1e2bc63b067e4145387e9d8422`
- Currencies: `SAR`
- Webhook events: 23

## Instruments

| Instrument | Title | States | Actions |
| --- | --- | --- | --- |
| [`payout_run`](../instruments/payout_run.md) | Payout run | 4 | cancel, create, withhold |

## Journeys

### Cancel a scheduled payout

- Journey id: `cancel_scheduled_payout`
- Steps: 7

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- customer.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- customer.customerId
4. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- customer.customerId
5. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- customer.customerId
6. `payout_run_create`
   - Actor: product
   - Action: `payout_run.create`
   - Route: `POST /v1/payout-runs`, scopes payout_run:write, idempotency required, receipt yes
   - Body: currency, earnerAccountId, netAmount, payoutFundingAccountId, productId, runAt, withholdingAccountId, withholdingAmount
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: earnerAccountId <- earner_account.accountId, payoutFundingAccountId <- funding_account.accountId, withholdingAccountId <- withholding_account.accountId
7. `payout_run_cancel`
   - Actor: product
   - Action: `payout_run.cancel`
   - Route: `POST /v1/payout-runs/{payoutRunId}/cancel`, scopes payout_run:write, idempotency required, receipt yes
   - Body: none
   - Path: payoutRunId
   - Query: none
   - Expect: none
   - Bindings: payoutRunId <- run.payoutRunId

### Onboard a creator

- Journey id: `creator_payouts_creator_onboarding`
- Steps: 2

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- creator.customerAccessId

### Run a disbursement cycle

- Journey id: `creator_payouts_run_cycle`
- Steps: 9

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- creator.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
4. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- earnings_account.accountId
5. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
6. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
7. `payout_run_create`
   - Actor: product
   - Action: `payout_run.create`
   - Route: `POST /v1/payout-runs`, scopes payout_run:write, idempotency required, receipt yes
   - Body: currency, earnerAccountId, netAmount, payoutFundingAccountId, productId, runAt, withholdingAccountId, withholdingAmount
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: earnerAccountId <- earnings_account.accountId, payoutFundingAccountId <- payout_account.accountId, withholdingAccountId <- withholding_account.accountId
8. `payout_run_withhold`
   - Actor: product
   - Action: `payout_run.withhold`
   - Route: `POST /v1/payout-runs/{payoutRunId}/withhold`, scopes payout_run:write, transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: payoutRunId
   - Query: none
   - Expect: none
   - Bindings: payoutRunId <- run.payoutRunId
9. `sandbox_platform_fire`
   - Actor: platform
   - Sandbox trigger: The platform fires `payout_run.execute` in normal lifecycle processing; sandbox fires it now.
   - Action: platform lifecycle trigger
   - Route: `POST /v1/sandbox/platform/fire`, scopes no scopes required, idempotency required, receipt yes
   - Body: input, operation
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: input.payoutRunId <- run.payoutRunId

### Create a creator payout

- Journey id: `creator_payouts_payout_creation`
- Steps: 8

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- creator.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
4. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- payout_account.accountId
5. `beneficiary_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/beneficiaries`, scopes transfer:write, idempotency required, receipt yes
   - Body: accountAddress, name
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
6. `beneficiary_verify`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/beneficiary-verifications`, scopes transfer:write, idempotency required, receipt yes
   - Body: beneficiaryName, iban
   - Path: none
   - Query: none
   - Expect: beneficiaryVerificationId, tenantId, iban, beneficiaryName, matchGrade
   - Bindings: none
7. `sandbox_beneficiary_accept`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/beneficiaries/{beneficiaryId}/accept`, scopes transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: beneficiaryId
   - Query: none
   - Expect: none
   - Bindings: beneficiaryId <- beneficiary.beneficiaryId
8. `payout_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/payouts`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, beneficiaryId, currency, sourceAccountId, speed
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sourceAccountId <- payout_account.accountId, beneficiaryId <- beneficiary.beneficiaryId

### Ledger an earnings cycle

- Journey id: `creator_payouts_earnings_cycle`
- Steps: 7

1. `sandbox_customer_onboard`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-onboarding`, scopes customer:write, idempotency required, receipt yes
   - Body: displayName, productId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: none
2. `sandbox_customer_access_activate`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/customer-access/{customerAccessId}/activate`, scopes customer:write, idempotency required, receipt yes
   - Body: none
   - Path: customerAccessId
   - Query: none
   - Expect: none
   - Bindings: customerAccessId <- creator.customerAccessId
3. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
4. `account_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/accounts`, scopes account:write, idempotency required, receipt yes
   - Body: currency, owner, role
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: owner.id <- creator.customerId
5. `sandbox_account_fund`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/sandbox/account-funding`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: destinationAccountId <- earnings_account.accountId
6. `internal_transfer_reserve`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/internal-transfers/reserve`, scopes transfer:write, idempotency required, receipt yes
   - Body: amount, currency, destinationAccountId, memo, sourceAccountId
   - Path: none
   - Query: none
   - Expect: none
   - Bindings: sourceAccountId <- earnings_account.accountId, destinationAccountId <- payout_account.accountId
7. `internal_transfer_post`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/internal-transfers/{transferId}/post`, scopes transfer:write, idempotency required, receipt yes
   - Body: none
   - Path: transferId
   - Query: none
   - Expect: none
   - Bindings: transferId <- earnings.transferId

### Register the payout organization

- Journey id: `creator_payouts_organization_registration`
- Steps: 1

1. `customer_create`
   - Actor: product
   - Action: platform write
   - Route: `POST /v1/customers`, scopes customer:write, idempotency required, receipt yes
   - Body: entity, productId
   - Path: none
   - Query: none
   - Expect: tenantId, productId, customerId, customerStatus, entityId, entityStatus, customerAccessId
   - Bindings: none

## Cost

Cost table version 2026-09-02.1. Flat amounts are multiplied by the action count; basis points price the meter's moved amount, which an action count does not determine.

| Instrument | Action | Effect | Meter | Flat per action | Rate on meter | 1,000 per month | 100,000 per month | 10,000,000 per month |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `payout_run` | `execute` | `moves.transfer.internal` | `transfer.internal.volume_sar` | 0.75 SAR | 11 bps | 750.00 SAR | 75,000.00 SAR | 7,500,000.00 SAR |
| `payout_run` | `execute` | `schedules.due` | `instrument.event.count` | 0.00 SAR | 0 bps | 0.00 SAR | 0.00 SAR | 0.00 SAR |
| `payout_run` | `withhold` | `moves.transfer.internal` | `transfer.internal.volume_sar` | 0.75 SAR | 11 bps | 750.00 SAR | 75,000.00 SAR | 7,500,000.00 SAR |
| **Total flat** | | | | | | **1,500.00 SAR** | **150,000.00 SAR** | **15,000,000.00 SAR** |