Stripe Connect payouts

One payment, separate partner earnings

Connect is an optional server API flow for US partners. Set a selling price for the cards; TCGPlaytest adds delivery and applicable tax, collects the customer payment and fulfills the order. Accept payout terms and finish onboarding in Dashboard → Payouts.

To test order confirmation, return handling and shipment notifications without Stripe, use a tcgp_test_ key with the same Connect cart fields. No payout onboarding is required for the checkout simulator. Prices, tax, fees and transfers are not exercised by this simulator.

Create a Connect cart

Keep your existing live partner API key on your server. Add settlement: "connect" and retail_amount_cents to the usual cart request. The amount is the entire cart's card-sale subtotal in USD cents, excluding shipping and tax, and must cover printing. It is immutable; changed artwork, quantities or price require a new cart and idempotency key. Build this price from your saved order on your server, never directly from browser input.

curl --request POST 'https://partner.tcgplaytest.com/v1/carts' \
  --header "Authorization: Bearer $TCGP_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: shop-order-1042-connect-v1' \
  --data '{
    "settlement": "connect",
    "retail_amount_cents": 2500,
    "external_ref": "shop-order-1042",
    "return_url": "https://your-store.example/order-complete",
    "items": [{"image_url": "https://your-store.example/artwork/front.png", "quantity": 10}]
  }'

Upload artwork and poll as usual. When open, use TCGPlaytest.checkout(cart) for delivery details on your website, followed by Stripe payment and your registered return URL. Verify signed order events before marking live orders paid. Connect does not allow affiliate discounts or another payment for the same cards.

How earnings and the reserve work

Partner earnings = card-sale subtotal − quoted printing cost − the actual Stripe fee on the customer payment. Shipping and collected tax stay with TCGPlaytest. Earnings cannot be negative; a processing-fee shortfall pauses transfers for review.

We transfer 95% of earnings after verifying payment. The other 5%, rounded up to a whole cent, becomes eligible for automatic transfer 15 days after payment. Worker scheduling and Stripe availability apply; arrival in a bank account follows Stripe's payout schedule. This reserve is not an extra fee.

Example only: $25 card sale − $10 printing − $1.20 actual processing fee = $13.80 earnings. $13.11 transfers first, and $0.69 is reserved. Actual Stripe fees vary; the integration reads the charge's balance transaction.

Keep prepaid credit separate

Connect carts never reserve or spend printing credit, even when a partner has a balance. Omitted or hosted settlement keeps the existing automatic credit-or-normal-checkout behavior. Explicit prepaid keeps the advanced prepaid API. Standalone widget carts continue the credit-or-normal-checkout flow; partner-set retail prices require the authenticated server API.

Refunds, disputes and account restrictions

Issue refunds through the platform Stripe account. Verified refunds reduce remaining partner earnings dollar-for-dollar, capped at those earnings; the worker reverses excess earlier transfers. Open or lost disputes stop releases and recover transfers where Stripe permits. Pending refunds, restricted accounts and unresolved recovery pause new transfers. Review outstanding recovery in Stripe; a reserve does not eliminate platform liability for refunds or disputes.

Operator setup

Run the Connect migration once on the partner database. Set PARTNER_CONNECT_ENABLED=true on both apps. Both apps must use the same Stripe platform account and payment environment. Keep the existing internal secret, origins and commerce webhook. Set the separate STRIPE_CONNECT_WEBHOOK_SECRET on the partner platform for https://partner.tcgplaytest.com/api/stripe/connect/webhook.

checkout.session.completed
checkout.session.expired
payment_intent.succeeded
charge.refunded
refund.created
refund.updated
refund.failed
charge.dispute.created
charge.dispute.updated
charge.dispute.closed
charge.dispute.funds_withdrawn
charge.dispute.funds_reinstated

These events belong to your platform account. Run the authenticated /api/internal/connect-maintenance cron every minute. Keep enough money in the platform Stripe balance to cover reserves; automatic bank payouts must not drain those funds before release. Current and past refunds are reconciled from Stripe, so repeated or unordered webhooks cannot create additional earnings.

Stripe test credentials use separate connected accounts and simulated transfers; they never create manufacturing orders. Changing credentials does not require different SQL. Finish pending test attempts before switching deployments to live; live accounts require onboarding and their live webhook secret. Complete live Stripe Tax settings before taking payments.