Clarify Rapyd marketplace architecture: split payments vs pay-in + payout

[DerpcatMusic]

Summary

The current repo already has a working Rapyd integration surface, but it does not implement the split-payment-on-pay-in flow described in the pasted architecture note. It currently uses hosted checkout for studio pay-in, then separate instructor payout orchestration.

What is real

• Rapyd Wallets are real and Rapyd docs describe split payments to 2-10 wallets.
• Rapyd docs also describe hosted beneficiary tokenization for payout onboarding.
• Rapyd docs expose bank transfer / bank_transfer payment method categories.
• This repo already has working Rapyd contract coverage and the tests passed locally.

What is not real or not supported as stated

• The repo does not send one payment directly split between instructor and platform wallets at checkout. It charges the studio, then later pays the instructor via payout flow.
• The specific claim that onboarding is done via POST /v1/user to create a wallet is not how this repo works; it uses hosted beneficiary onboarding / external recipient references.
• The claim that every instructor must pass Rapyd identity verification before receiving a shekel is stronger than what I could verify from docs and code. This repo currently gates payout onboarding on Didit verification instead.
• Fee and FX claims in the note are assumptions until verified against the live Rapyd account and pricing contract.

Repo state checked

• convex/rapyd.ts: hosted checkout creation and hosted beneficiary onboarding.
• convex/payments.ts and convex/payouts.ts: pay-in ledger, webhook processing, payout orchestration.
• convex/http.ts: Rapyd webhook route is already registered.
• Contract tests passed: bun test tests/contracts/rapyd-integration.contract.test.ts tests/contracts/finance-rapyd.contract.test.ts tests/contracts/payout-withdrawal.contract.test.ts.

Recommended next step

Decide between these two paths:

1. Keep the current architecture: studio pay-in + instructor payout, and document it as the supported flow.
2. Replace it with true Rapyd split-pay-on-checkout, but only after verifying Israel account capability and exact payout/bank-transfer support in the live Rapyd tenant.

Links

• Split payment by amount: https://docs.rapyd.net/en/split-payment-by-amount.html
• Wallet: https://docs.rapyd.net/en/wallet.html
• Configuring payment methods: https://docs.rapyd.net/en/configuring-list-of-payment-methods.html
• Beneficiary tokenization: https://docs.rapyd.net/en/create-beneficiary-tokenization-page.html