Payments Overview

Ring routes buyer rails (card | paypal | credit_balance | native_token) through PaymentConductor (lib/payments/conductor/). The card rail settles via WayForPay or Stripe (payment.cardPaymentProcessor / purpose env) — UI never picks a PSP id. Browser handoff is Conductor CheckoutRedirect (navigate | form_post) via followCheckoutResult. Rates and presentment come from Ring Oracle.

Rails comparison

Canonical PSP webhooks (settlement): POST /api/payments/{wayforpay,stripe,paypal}/webhook. Money truth for WayForPay: serviceUrl Approved settles — browser returnUrl is UX only.

What PaymentConductor covers

Extended purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor — details on PaymentConductor.

Membership native pay is membership_upgrade + native_token through PaymentConductor (soft launch: treasury SPL + ledger; deployed: on-chain RingMembership), then SubscriptionConductor ledger-only via metadata.tx_hash — see SubscriptionConductor. Its gate is payment.supportedMethods (isPaymentMethodEnabled('native_token')), not PAYMENT_STORE_ALLOW_TOKEN.

Idempotency: native pay (store + membership) follows the shared contract — one client idempotencyKey per intent; paid rows replay (same txHash), in-flight rows return 409 IDEMPOTENCY_IN_FLIGHT.

Native refunds: POST /api/admin/payments/[orderReference]/refund (platform admin or owning vendor; full-amount, idempotent, marks payment_transactions refunded).

Recommended path

Skill / desk: Cursor + Ring docs cluster — start from operator checklist Payment Gateway Integration, then deep-dive PaymentConductor.

Starter prompt (does not mutate until you approve env/config changes):

Configure this clone’s PaymentConductor: set PAYMENT_DEFAULT_PROCESSOR, WayForPay or Stripe credentials from env.local.template, enable store rails (card + optional credit/token/PayPal flags), register https://YOUR_HOST/api/payments/{processor}/webhook, and verify store checkout uses placeAndPayStoreOrder + CheckoutRedirect — no /api/cart payment routes.

Inputs checklist: clone host · ring-config.json payment.* · PSP cabinet credentials · webhook URL reachable from the internet · data/migrations/004_payment_transactions.sql applied.

Manual path

1. 1

   Choose card processor and rails

   Set payment.cardPaymentProcessor (wayforpay or stripe) and payment.gateways.*.enabled in ring-config.json. Optional per-purpose env: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR.

2. 2

   Fill credentials from templates

   Copy WayForPay / Stripe / PayPal keys from env.local.template (also docker.env.template). WayForPay SSOT: WAYFORPAY_MERCHANT_ACCOUNT, WAYFORPAY_SECRET_KEY, WAYFORPAY_MERCHANT_PASSWORD, WAYFORPAY_DOMAIN, WAYFORPAY_API_URL — no WAYFORPAY_MERCHANT_ID.

3. 3

   Enable optional store rails

   • Credit: keep PAYMENT_STORE_ALLOW_CREDIT / NEXT_PUBLIC_PAYMENT_STORE_ALLOW_CREDIT from disabling credit.
   • Native token: PAYMENT_STORE_ALLOW_TOKEN=true and NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN=true.
   • PayPal: NEXT_PUBLIC_PAYMENT_STORE_ALLOW_PAYPAL=true, gateways.paypal.enabled: true, plus PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID / PAYPAL_MODE.
4. 4

   Register webhooks and migrate ledger

   Register cabinet callbacks to /api/payments/wayforpay/webhook (and Stripe/PayPal twins). Apply 004_payment_transactions.sql before production traffic.

5. 5

   Smoke-test browser handoff

   Place a store order (card rail). Expect CheckoutRedirect — WayForPay HPP via POST form, not a GET query URL. Confirm settlement only after webhook Approved / capture — not on return URL alone.

Frequently asked questions

Impact

Will my clone need a separate cart payment microservice?

No. Store checkout places the order and pays through PaymentConductor (Server Action or the store payment routes above). There is no fabricated cart checkout REST API.

Does enabling PayPal change the card processor?

No. PayPal is its own rail. Card still resolves to WayForPay or Stripe independently.

Migration

We used to document brand buttons in the UI — what now?

Switch copy and components to rails (card / paypal / credit_balance / native_token). Keep processor selection in config/env. See PaymentConductor.

How do recurring memberships migrate off one-shot Orders?

Use SubscriptionConductor (PayPal Subscriptions v1, Stripe Subscriptions, WayForPay regularApi, credit, native, NFT gate). PaymentConductor still owns one-shot membership upgrades and store Orders.

Ops

Why did the member return from HPP without credit/order paid?

For WayForPay, settlement is serviceUrl webhook Approved — not returnUrl. Check cabinet webhook URL, HMAC secrets, and dispatcher logs.

Where do founders see payments in admin?

User detail Payments tab → GET /api/admin/users/[id]/payments (membership / wallet top-up and other ledger rows).

Related documentation

Payments Overview

Ring routes buyer rails (card | paypal | credit_balance | native_token) through PaymentConductor (lib/payments/conductor/). The card rail settles via WayForPay or Stripe (payment.cardPaymentProcessor / purpose env) — UI never picks a PSP id. Browser handoff is Conductor CheckoutRedirect (navigate | form_post) via followCheckoutResult. Rates and presentment come from Ring Oracle.

Rails comparison

Canonical PSP webhooks (settlement): POST /api/payments/{wayforpay,stripe,paypal}/webhook. Money truth for WayForPay: serviceUrl Approved settles — browser returnUrl is UX only.

What PaymentConductor covers

Extended purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor — details on PaymentConductor.

Membership native pay is membership_upgrade + native_token through PaymentConductor (soft launch: treasury SPL + ledger; deployed: on-chain RingMembership), then SubscriptionConductor ledger-only via metadata.tx_hash — see SubscriptionConductor. Its gate is payment.supportedMethods (isPaymentMethodEnabled('native_token')), not PAYMENT_STORE_ALLOW_TOKEN.

Idempotency: native pay (store + membership) follows the shared contract — one client idempotencyKey per intent; paid rows replay (same txHash), in-flight rows return 409 IDEMPOTENCY_IN_FLIGHT.

Native refunds: POST /api/admin/payments/[orderReference]/refund (platform admin or owning vendor; full-amount, idempotent, marks payment_transactions refunded).

Recommended path

Skill / desk: Cursor + Ring docs cluster — start from operator checklist Payment Gateway Integration, then deep-dive PaymentConductor.

Starter prompt (does not mutate until you approve env/config changes):

Configure this clone’s PaymentConductor: set PAYMENT_DEFAULT_PROCESSOR, WayForPay or Stripe credentials from env.local.template, enable store rails (card + optional credit/token/PayPal flags), register https://YOUR_HOST/api/payments/{processor}/webhook, and verify store checkout uses placeAndPayStoreOrder + CheckoutRedirect — no /api/cart payment routes.

Inputs checklist: clone host · ring-config.json payment.* · PSP cabinet credentials · webhook URL reachable from the internet · data/migrations/004_payment_transactions.sql applied.

Manual path

1. 1

   Choose card processor and rails

   Set payment.cardPaymentProcessor (wayforpay or stripe) and payment.gateways.*.enabled in ring-config.json. Optional per-purpose env: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR.

2. 2

   Fill credentials from templates

   Copy WayForPay / Stripe / PayPal keys from env.local.template (also docker.env.template). WayForPay SSOT: WAYFORPAY_MERCHANT_ACCOUNT, WAYFORPAY_SECRET_KEY, WAYFORPAY_MERCHANT_PASSWORD, WAYFORPAY_DOMAIN, WAYFORPAY_API_URL — no WAYFORPAY_MERCHANT_ID.

3. 3

   Enable optional store rails

   • Credit: keep PAYMENT_STORE_ALLOW_CREDIT / NEXT_PUBLIC_PAYMENT_STORE_ALLOW_CREDIT from disabling credit.
   • Native token: PAYMENT_STORE_ALLOW_TOKEN=true and NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN=true.
   • PayPal: NEXT_PUBLIC_PAYMENT_STORE_ALLOW_PAYPAL=true, gateways.paypal.enabled: true, plus PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID / PAYPAL_MODE.
4. 4

   Register webhooks and migrate ledger

   Register cabinet callbacks to /api/payments/wayforpay/webhook (and Stripe/PayPal twins). Apply 004_payment_transactions.sql before production traffic.

5. 5

   Smoke-test browser handoff

   Place a store order (card rail). Expect CheckoutRedirect — WayForPay HPP via POST form, not a GET query URL. Confirm settlement only after webhook Approved / capture — not on return URL alone.

Frequently asked questions

Impact

Will my clone need a separate cart payment microservice?

No. Store checkout places the order and pays through PaymentConductor (Server Action or the store payment routes above). There is no fabricated cart checkout REST API.

Does enabling PayPal change the card processor?

No. PayPal is its own rail. Card still resolves to WayForPay or Stripe independently.

Migration

We used to document brand buttons in the UI — what now?

Switch copy and components to rails (card / paypal / credit_balance / native_token). Keep processor selection in config/env. See PaymentConductor.

How do recurring memberships migrate off one-shot Orders?

Use SubscriptionConductor (PayPal Subscriptions v1, Stripe Subscriptions, WayForPay regularApi, credit, native, NFT gate). PaymentConductor still owns one-shot membership upgrades and store Orders.

Ops

Why did the member return from HPP without credit/order paid?

For WayForPay, settlement is serviceUrl webhook Approved — not returnUrl. Check cabinet webhook URL, HMAC secrets, and dispatcher logs.

Where do founders see payments in admin?

User detail Payments tab → GET /api/admin/users/[id]/payments (membership / wallet top-up and other ledger rows).

Related documentation

Payments Overview

Ring routes buyer rails (card | paypal | credit_balance | native_token) through PaymentConductor (lib/payments/conductor/). The card rail settles via WayForPay or Stripe (payment.cardPaymentProcessor / purpose env) — UI never picks a PSP id. Browser handoff is Conductor CheckoutRedirect (navigate | form_post) via followCheckoutResult. Rates and presentment come from Ring Oracle.

Rails comparison

Canonical PSP webhooks (settlement): POST /api/payments/{wayforpay,stripe,paypal}/webhook. Money truth for WayForPay: serviceUrl Approved settles — browser returnUrl is UX only.

What PaymentConductor covers

Extended purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor — details on PaymentConductor.

Membership native pay is membership_upgrade + native_token through PaymentConductor (soft launch: treasury SPL + ledger; deployed: on-chain RingMembership), then SubscriptionConductor ledger-only via metadata.tx_hash — see SubscriptionConductor. Its gate is payment.supportedMethods (isPaymentMethodEnabled('native_token')), not PAYMENT_STORE_ALLOW_TOKEN.

Idempotency: native pay (store + membership) follows the shared contract — one client idempotencyKey per intent; paid rows replay (same txHash), in-flight rows return 409 IDEMPOTENCY_IN_FLIGHT.

Native refunds: POST /api/admin/payments/[orderReference]/refund (platform admin or owning vendor; full-amount, idempotent, marks payment_transactions refunded).

Recommended path

Skill / desk: Cursor + Ring docs cluster — start from operator checklist Payment Gateway Integration, then deep-dive PaymentConductor.

Starter prompt (does not mutate until you approve env/config changes):

Configure this clone’s PaymentConductor: set PAYMENT_DEFAULT_PROCESSOR, WayForPay or Stripe credentials from env.local.template, enable store rails (card + optional credit/token/PayPal flags), register https://YOUR_HOST/api/payments/{processor}/webhook, and verify store checkout uses placeAndPayStoreOrder + CheckoutRedirect — no /api/cart payment routes.

Inputs checklist: clone host · ring-config.json payment.* · PSP cabinet credentials · webhook URL reachable from the internet · data/migrations/004_payment_transactions.sql applied.

Manual path

1. 1

   Choose card processor and rails

   Set payment.cardPaymentProcessor (wayforpay or stripe) and payment.gateways.*.enabled in ring-config.json. Optional per-purpose env: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR.

2. 2

   Fill credentials from templates

   Copy WayForPay / Stripe / PayPal keys from env.local.template (also docker.env.template). WayForPay SSOT: WAYFORPAY_MERCHANT_ACCOUNT, WAYFORPAY_SECRET_KEY, WAYFORPAY_MERCHANT_PASSWORD, WAYFORPAY_DOMAIN, WAYFORPAY_API_URL — no WAYFORPAY_MERCHANT_ID.

3. 3

   Enable optional store rails

   • Credit: keep PAYMENT_STORE_ALLOW_CREDIT / NEXT_PUBLIC_PAYMENT_STORE_ALLOW_CREDIT from disabling credit.
   • Native token: PAYMENT_STORE_ALLOW_TOKEN=true and NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN=true.
   • PayPal: NEXT_PUBLIC_PAYMENT_STORE_ALLOW_PAYPAL=true, gateways.paypal.enabled: true, plus PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID / PAYPAL_MODE.
4. 4

   Register webhooks and migrate ledger

   Register cabinet callbacks to /api/payments/wayforpay/webhook (and Stripe/PayPal twins). Apply 004_payment_transactions.sql before production traffic.

5. 5

   Smoke-test browser handoff

   Place a store order (card rail). Expect CheckoutRedirect — WayForPay HPP via POST form, not a GET query URL. Confirm settlement only after webhook Approved / capture — not on return URL alone.

Frequently asked questions

Impact

Will my clone need a separate cart payment microservice?

No. Store checkout places the order and pays through PaymentConductor (Server Action or the store payment routes above). There is no fabricated cart checkout REST API.

Does enabling PayPal change the card processor?

No. PayPal is its own rail. Card still resolves to WayForPay or Stripe independently.

Migration

We used to document brand buttons in the UI — what now?

Switch copy and components to rails (card / paypal / credit_balance / native_token). Keep processor selection in config/env. See PaymentConductor.

How do recurring memberships migrate off one-shot Orders?

Use SubscriptionConductor (PayPal Subscriptions v1, Stripe Subscriptions, WayForPay regularApi, credit, native, NFT gate). PaymentConductor still owns one-shot membership upgrades and store Orders.

Ops

Why did the member return from HPP without credit/order paid?

For WayForPay, settlement is serviceUrl webhook Approved — not returnUrl. Check cabinet webhook URL, HMAC secrets, and dispatcher logs.

Where do founders see payments in admin?

User detail Payments tab → GET /api/admin/users/[id]/payments (membership / wallet top-up and other ledger rows).

Related documentation

Operator scenarios

• Launch UA store — WayForPay credentials + default processor; keep credit on for members; defer PayPal until PAYPAL_* is ready.
• International card — set PAYMENT_DEFAULT_PROCESSOR=stripe (or purpose overrides); same rails UI.
• DAO jar fundraising — enable public-pool card checkout; fees via publicPools.platformFeePercentByRole — not donation products.
• Admin visibility — user detail Payments tab lists ledger rows (GET /api/admin/users/[id]/payments).

ring-config.json payment section

Symbols are examples — replace with your clone’s store.mainCurrency and tokens.nativeToken.symbol.

UI store rails are driven by getClientStorePaymentRails() (env + gateways) — not by inventing PSP buttons.

Verified store payment routes (not cart REST)

There is no /api/cart/... payment surface. Cart state stays client/feature-store; money always enters via Conductor.

Environment (excerpt)

Templates: env.local.template, docker.env.template, docker-compose.template.yml. Ledger: data/migrations/004_payment_transactions.sql.

Deep-dive: CheckoutRedirect DTO, idempotency, and webhook dispatcher.

Operator scenarios

• Launch UA store — WayForPay credentials + default processor; keep credit on for members; defer PayPal until PAYPAL_* is ready.
• International card — set PAYMENT_DEFAULT_PROCESSOR=stripe (or purpose overrides); same rails UI.
• DAO jar fundraising — enable public-pool card checkout; fees via publicPools.platformFeePercentByRole — not donation products.
• Admin visibility — user detail Payments tab lists ledger rows (GET /api/admin/users/[id]/payments).

ring-config.json payment section

Symbols are examples — replace with your clone’s store.mainCurrency and tokens.nativeToken.symbol.

UI store rails are driven by getClientStorePaymentRails() (env + gateways) — not by inventing PSP buttons.

Verified store payment routes (not cart REST)

There is no /api/cart/... payment surface. Cart state stays client/feature-store; money always enters via Conductor.

Environment (excerpt)

Templates: env.local.template, docker.env.template, docker-compose.template.yml. Ledger: data/migrations/004_payment_transactions.sql.

Deep-dive: CheckoutRedirect DTO, idempotency, and webhook dispatcher.

Operator scenarios

• Launch UA store — WayForPay credentials + default processor; keep credit on for members; defer PayPal until PAYPAL_* is ready.
• International card — set PAYMENT_DEFAULT_PROCESSOR=stripe (or purpose overrides); same rails UI.
• DAO jar fundraising — enable public-pool card checkout; fees via publicPools.platformFeePercentByRole — not donation products.
• Admin visibility — user detail Payments tab lists ledger rows (GET /api/admin/users/[id]/payments).

ring-config.json payment section

Symbols are examples — replace with your clone’s store.mainCurrency and tokens.nativeToken.symbol.

UI store rails are driven by getClientStorePaymentRails() (env + gateways) — not by inventing PSP buttons.

Verified store payment routes (not cart REST)

There is no /api/cart/... payment surface. Cart state stays client/feature-store; money always enters via Conductor.

Environment (excerpt)

Templates: env.local.template, docker.env.template, docker-compose.template.yml. Ledger: data/migrations/004_payment_transactions.sql.

Deep-dive: CheckoutRedirect DTO, idempotency, and webhook dispatcher.