PaymentConductor

PaymentConductor is Ring's config-driven payment layer. One ledger (payment_transactions) and one webhook dispatcher serve store, membership, news promotion, wallet credit top-up, and public pool (DAO jar) card/PayPal chip-ins. Browser UIs never open a PSP by brand — they follow Conductor CheckoutRedirect via followCheckoutResult (lib/payments/checkout-redirect.ts). Deep types and sequences: PaymentConductor architecture.

Rail vs processor (comparison)

Buyers pick a rail. Conductor persists a processor on the ledger row. Card rail resolves to WayForPay or Stripe via getPaymentProvider(purpose) — never from UI brand strings.

Payment purposes

Additional typed purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor + dispatcher pattern with matching handlers under lib/payments/conductor/handlers/.

Recommended path

Use Cursor skill international-payment-systems-specialist (or UA WayForPay desk commerce-ua-dropshipping-woocommerce-wayforpay-guru) with this starter prompt — review the plan before mutating env/secrets:

“Configure Ring PaymentConductor for this clone: set PAYMENT_DEFAULT_PROCESSOR and purpose overrides, enable rails in ring-config.json payment.gateways, wire WayForPay/Stripe/PayPal credentials from env.local.template, register canonical webhooks under /api/payments/*/webhook, and smoke-test store + wallet_topup. Do not invent routes or fee contracts.”

Inputs checklist: clone domain / public base URL · merchant PSP dashboard access · ring-config.json payment block · secrets only in env (never MDX) · pause for approval before writing production secrets.

Operator walkthrough (non-agent): Payment integration · WayForPay.

Manual path

Frequently asked questions

Impact

Will credit top-up mint RING?

No. wallet_topup adds fiat credit points. On-chain RING buy paths are Token Desk / confidential onramp — not this purpose.

Will swapping PAYMENT_DEFAULT_PROCESSOR rewrite store UI?

No. UI follows rails + CheckoutRedirect. Processor is resolved server-side per purpose.

Migration

Do I keep legacy WayForPay webhook URLs?

Prefer canonical /api/payments/wayforpay/webhook. Legacy store/news webhook routes may still delegate — point new PSP dashboard entries at the canonical path.

What env name accepts UAH store orders when points are USD?

PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (comma-separated), or store.creditBalanceAcceptedOrderCurrencies in config — not the older PAYMENT_CREDIT_ACCEPT_ORDER_CURRENCY spelling.

Ops

Why did WayForPay checkout “open but fail”?

HPP requires form POST (form_post). Opening the URL as GET breaks the session.

What happens when a client retries with the same idempotency key?

A paid row replays (same txHash, no second charge); an in-flight row returns 409 IDEMPOTENCY_IN_FLIGHT. Never retry with a fresh key after a timeout — reuse the intent key.

Who can refund a native payment?

Platform admin for any native row; a vendor can refund store_order native payments of their own store (order vendorSettlements match). Refunds are full-amount, idempotent, and mark only payment_transactions refunded.

Where do admins see membership/top-up rows?

GET /api/admin/users/[id]/payments (platform admin). Defaults focus on membership_upgrade and wallet_topup.

Related documentation

PaymentConductor

PaymentConductor is Ring's config-driven payment layer. One ledger (payment_transactions) and one webhook dispatcher serve store, membership, news promotion, wallet credit top-up, and public pool (DAO jar) card/PayPal chip-ins. Browser UIs never open a PSP by brand — they follow Conductor CheckoutRedirect via followCheckoutResult (lib/payments/checkout-redirect.ts). Deep types and sequences: PaymentConductor architecture.

Rail vs processor (comparison)

Buyers pick a rail. Conductor persists a processor on the ledger row. Card rail resolves to WayForPay or Stripe via getPaymentProvider(purpose) — never from UI brand strings.

Payment purposes

Additional typed purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor + dispatcher pattern with matching handlers under lib/payments/conductor/handlers/.

Recommended path

Use Cursor skill international-payment-systems-specialist (or UA WayForPay desk commerce-ua-dropshipping-woocommerce-wayforpay-guru) with this starter prompt — review the plan before mutating env/secrets:

“Configure Ring PaymentConductor for this clone: set PAYMENT_DEFAULT_PROCESSOR and purpose overrides, enable rails in ring-config.json payment.gateways, wire WayForPay/Stripe/PayPal credentials from env.local.template, register canonical webhooks under /api/payments/*/webhook, and smoke-test store + wallet_topup. Do not invent routes or fee contracts.”

Inputs checklist: clone domain / public base URL · merchant PSP dashboard access · ring-config.json payment block · secrets only in env (never MDX) · pause for approval before writing production secrets.

Operator walkthrough (non-agent): Payment integration · WayForPay.

Manual path

Frequently asked questions

Impact

Will credit top-up mint RING?

No. wallet_topup adds fiat credit points. On-chain RING buy paths are Token Desk / confidential onramp — not this purpose.

Will swapping PAYMENT_DEFAULT_PROCESSOR rewrite store UI?

No. UI follows rails + CheckoutRedirect. Processor is resolved server-side per purpose.

Migration

Do I keep legacy WayForPay webhook URLs?

Prefer canonical /api/payments/wayforpay/webhook. Legacy store/news webhook routes may still delegate — point new PSP dashboard entries at the canonical path.

What env name accepts UAH store orders when points are USD?

PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (comma-separated), or store.creditBalanceAcceptedOrderCurrencies in config — not the older PAYMENT_CREDIT_ACCEPT_ORDER_CURRENCY spelling.

Ops

Why did WayForPay checkout “open but fail”?

HPP requires form POST (form_post). Opening the URL as GET breaks the session.

What happens when a client retries with the same idempotency key?

A paid row replays (same txHash, no second charge); an in-flight row returns 409 IDEMPOTENCY_IN_FLIGHT. Never retry with a fresh key after a timeout — reuse the intent key.

Who can refund a native payment?

Platform admin for any native row; a vendor can refund store_order native payments of their own store (order vendorSettlements match). Refunds are full-amount, idempotent, and mark only payment_transactions refunded.

Where do admins see membership/top-up rows?

GET /api/admin/users/[id]/payments (platform admin). Defaults focus on membership_upgrade and wallet_topup.

Related documentation

PaymentConductor

PaymentConductor is Ring's config-driven payment layer. One ledger (payment_transactions) and one webhook dispatcher serve store, membership, news promotion, wallet credit top-up, and public pool (DAO jar) card/PayPal chip-ins. Browser UIs never open a PSP by brand — they follow Conductor CheckoutRedirect via followCheckoutResult (lib/payments/checkout-redirect.ts). Deep types and sequences: PaymentConductor architecture.

Rail vs processor (comparison)

Buyers pick a rail. Conductor persists a processor on the ledger row. Card rail resolves to WayForPay or Stripe via getPaymentProvider(purpose) — never from UI brand strings.

Payment purposes

Additional typed purposes (project_order, task_escrow, collective_order_slot, scheduled_service_slot) share the same Conductor + dispatcher pattern with matching handlers under lib/payments/conductor/handlers/.

Recommended path

Use Cursor skill international-payment-systems-specialist (or UA WayForPay desk commerce-ua-dropshipping-woocommerce-wayforpay-guru) with this starter prompt — review the plan before mutating env/secrets:

“Configure Ring PaymentConductor for this clone: set PAYMENT_DEFAULT_PROCESSOR and purpose overrides, enable rails in ring-config.json payment.gateways, wire WayForPay/Stripe/PayPal credentials from env.local.template, register canonical webhooks under /api/payments/*/webhook, and smoke-test store + wallet_topup. Do not invent routes or fee contracts.”

Inputs checklist: clone domain / public base URL · merchant PSP dashboard access · ring-config.json payment block · secrets only in env (never MDX) · pause for approval before writing production secrets.

Operator walkthrough (non-agent): Payment integration · WayForPay.

Manual path

Frequently asked questions

Impact

Will credit top-up mint RING?

No. wallet_topup adds fiat credit points. On-chain RING buy paths are Token Desk / confidential onramp — not this purpose.

Will swapping PAYMENT_DEFAULT_PROCESSOR rewrite store UI?

No. UI follows rails + CheckoutRedirect. Processor is resolved server-side per purpose.

Migration

Do I keep legacy WayForPay webhook URLs?

Prefer canonical /api/payments/wayforpay/webhook. Legacy store/news webhook routes may still delegate — point new PSP dashboard entries at the canonical path.

What env name accepts UAH store orders when points are USD?

PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (comma-separated), or store.creditBalanceAcceptedOrderCurrencies in config — not the older PAYMENT_CREDIT_ACCEPT_ORDER_CURRENCY spelling.

Ops

Why did WayForPay checkout “open but fail”?

HPP requires form POST (form_post). Opening the URL as GET breaks the session.

What happens when a client retries with the same idempotency key?

A paid row replays (same txHash, no second charge); an in-flight row returns 409 IDEMPOTENCY_IN_FLIGHT. Never retry with a fresh key after a timeout — reuse the intent key.

Who can refund a native payment?

Platform admin for any native row; a vendor can refund store_order native payments of their own store (order vendorSettlements match). Refunds are full-amount, idempotent, and mark only payment_transactions refunded.

Where do admins see membership/top-up rows?

GET /api/admin/users/[id]/payments (platform admin). Defaults focus on membership_upgrade and wallet_topup.

Related documentation

1. 1

   Pick default card processor

   Set PAYMENT_DEFAULT_PROCESSOR=wayforpay (UA/UAH-first) or stripe (USD-first). Optional purpose overrides: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR (blank → default).

2. 2

   Enable gateways and rails in config

   In ring-config.json, set payment.cardPaymentProcessor, payment.supportedMethods, and payment.gateways.*.enabled. Fee % / feeFixedCents there are clone config defaults for display/estimation — not a guarantee of the PSP’s live schedule.

3. 3

   Wire credentials

   From env.local.template: WAYFORPAY_MERCHANT_ACCOUNT + WAYFORPAY_SECRET_KEY (+ WAYFORPAY_MERCHANT_PASSWORD for recurring/regularApi); or STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET; for PayPal PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID (+ membership plan ids when using Subscriptions). There is no WAYFORPAY_MERCHANT_ID.

4. 4

   Register canonical webhooks

   Point each PSP dashboard to:

   Endpoint	Provider verify
   POST /api/payments/wayforpay/webhook	WayForPay HMAC → dispatchWayForPayWebhook
   POST /api/payments/stripe/webhook	STRIPE_WEBHOOK_SECRET → dispatchStripeWebhook
   POST /api/payments/paypal/webhook	Transmission signature + PAYPAL_WEBHOOK_ID → dispatchPayPalWebhook

   Apply data/migrations/004_payment_transactions.sql before production ledger use.

5. 5

   Smoke checkout handoff

   Create a checkout through Conductor; UI must call followCheckoutResult / followCheckoutRedirect. Expect navigate (Stripe/PayPal/invoice URL) or form_post (WayForPay HPP). Confirm ledger row → handler fulfillment after webhook (or sync mark-paid for credit/token).

Quick setup sketch

PaymentProcessorId: wayforpay | stripe | paypal | credit_balance | native_token.

Webhook ingress (verified)

Store routes (verified)

Native token — checkout, idempotency, refunds (verified)

Store checkout UI. The token rail is enabled in features/store/components/checkout/payment-step.tsx via getClientStorePaymentRails(): NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN === 'true' and payment.gateways.native_token.enabled !== false. Server-side gate stays isRailEnabled('store_order','native_token') (PAYMENT_STORE_ALLOW_TOKEN=true). The checkout flow posts placeAndPayStoreOrder (server action) or POST /api/store/payments/token — both route through PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'native_token' }) → createNativeTokenCheckout (balance check → treasury SPL transfer → payment_transactions createPending → markPaid).

Membership native pay. POST /api/membership/payment/token is the single chokepoint (UI: components/membership/ring-payment-modal.tsx). Gate: isRailEnabled('membership_upgrade','native_token') reads isPaymentMethodEnabled('native_token') (payment.supportedMethods SSOT) — not the store flag, so membership native works with PAYMENT_STORE_ALLOW_TOKEN unset. Composition (ledger parity with card):

Idempotency contract (same as desk orders / NFT listings / public-pool contributions). Clients generate one UUID per payment intent (crypto.randomUUID() in checkout-client.tsx / ring-payment-modal.tsx) and reuse it on retry. payment_transactions rows carry a top-level idempotency_key; before charging, findByIdempotencyKey(userId, purpose, key) replays a paid row (same txHash, zero treasury movement) or returns 409 IDEMPOTENCY_IN_FLIGHT for an in-flight row. Old clients without a key keep the previous behavior.

Native refunds. POST /api/admin/payments/[orderReference]/refund — platform admin (any native payment) or vendor who owns the store order (order vendorSettlements ∩ getVendorEntities). Idempotent by orderReference (already-refunded replays refundTxHash); full-amount only; treasury→user via transferTokenFromTreasury; ledger gets status refunded + refundTxHash in processor_payload. Transfer failure keeps the row paid (retryable). Minimal scope — no subscription_ledger / order-status flip.

Ledger precision. Native-token rows store amount_minor in token precision (tokenAmount × 1e6, currency = token symbol); the main-currency stamp is skipped for token-denominated rows (fx_rate remains valid) — see stampMainCurrencyFx.

Wallet top-up (verified)

initiateCreditTopupPayment (app/_actions/wallet.ts) → WalletConductor.initiateTopUp → purpose wallet_topup → webhook wallet-topup*.ts → creditBalanceService.addFiatUsd (1:1 points). Distinct from native_token spend and from confidential native_token_onramp.

Public pool jar (verified)

POST /api/public-pools/[slug]/card-checkout → public_pool_contribution → desk FX → settlePublicPoolCardContribution. Native SPL chip-ins stay on contributeToPool (not Conductor).

Membership PayPal (verified)

POST /api/membership/payment/paypal → SubscriptionConductor provider paypal: recurring → Subscriptions v1 lifecycle webhooks; one-shot → Conductor Orders capture → recordPaidSubscription. UI: components/membership/payment-modal.tsx when public PayPal flag is on.

Ledger

data/migrations/004_payment_transactions.sql. Rows via DatabaseService / payment transaction service — result contract { success, data, error }.

Deep-dive: CheckoutRedirect DTO, dispatcher sequences, and API route map.

1. 1

   Pick default card processor

   Set PAYMENT_DEFAULT_PROCESSOR=wayforpay (UA/UAH-first) or stripe (USD-first). Optional purpose overrides: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR (blank → default).

2. 2

   Enable gateways and rails in config

   In ring-config.json, set payment.cardPaymentProcessor, payment.supportedMethods, and payment.gateways.*.enabled. Fee % / feeFixedCents there are clone config defaults for display/estimation — not a guarantee of the PSP’s live schedule.

3. 3

   Wire credentials

   From env.local.template: WAYFORPAY_MERCHANT_ACCOUNT + WAYFORPAY_SECRET_KEY (+ WAYFORPAY_MERCHANT_PASSWORD for recurring/regularApi); or STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET; for PayPal PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID (+ membership plan ids when using Subscriptions). There is no WAYFORPAY_MERCHANT_ID.

4. 4

   Register canonical webhooks

   Point each PSP dashboard to:

   Endpoint	Provider verify
   POST /api/payments/wayforpay/webhook	WayForPay HMAC → dispatchWayForPayWebhook
   POST /api/payments/stripe/webhook	STRIPE_WEBHOOK_SECRET → dispatchStripeWebhook
   POST /api/payments/paypal/webhook	Transmission signature + PAYPAL_WEBHOOK_ID → dispatchPayPalWebhook

   Apply data/migrations/004_payment_transactions.sql before production ledger use.

5. 5

   Smoke checkout handoff

   Create a checkout through Conductor; UI must call followCheckoutResult / followCheckoutRedirect. Expect navigate (Stripe/PayPal/invoice URL) or form_post (WayForPay HPP). Confirm ledger row → handler fulfillment after webhook (or sync mark-paid for credit/token).

Quick setup sketch

PaymentProcessorId: wayforpay | stripe | paypal | credit_balance | native_token.

Webhook ingress (verified)

Store routes (verified)

Native token — checkout, idempotency, refunds (verified)

Store checkout UI. The token rail is enabled in features/store/components/checkout/payment-step.tsx via getClientStorePaymentRails(): NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN === 'true' and payment.gateways.native_token.enabled !== false. Server-side gate stays isRailEnabled('store_order','native_token') (PAYMENT_STORE_ALLOW_TOKEN=true). The checkout flow posts placeAndPayStoreOrder (server action) or POST /api/store/payments/token — both route through PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'native_token' }) → createNativeTokenCheckout (balance check → treasury SPL transfer → payment_transactions createPending → markPaid).

Membership native pay. POST /api/membership/payment/token is the single chokepoint (UI: components/membership/ring-payment-modal.tsx). Gate: isRailEnabled('membership_upgrade','native_token') reads isPaymentMethodEnabled('native_token') (payment.supportedMethods SSOT) — not the store flag, so membership native works with PAYMENT_STORE_ALLOW_TOKEN unset. Composition (ledger parity with card):

Idempotency contract (same as desk orders / NFT listings / public-pool contributions). Clients generate one UUID per payment intent (crypto.randomUUID() in checkout-client.tsx / ring-payment-modal.tsx) and reuse it on retry. payment_transactions rows carry a top-level idempotency_key; before charging, findByIdempotencyKey(userId, purpose, key) replays a paid row (same txHash, zero treasury movement) or returns 409 IDEMPOTENCY_IN_FLIGHT for an in-flight row. Old clients without a key keep the previous behavior.

Native refunds. POST /api/admin/payments/[orderReference]/refund — platform admin (any native payment) or vendor who owns the store order (order vendorSettlements ∩ getVendorEntities). Idempotent by orderReference (already-refunded replays refundTxHash); full-amount only; treasury→user via transferTokenFromTreasury; ledger gets status refunded + refundTxHash in processor_payload. Transfer failure keeps the row paid (retryable). Minimal scope — no subscription_ledger / order-status flip.

Ledger precision. Native-token rows store amount_minor in token precision (tokenAmount × 1e6, currency = token symbol); the main-currency stamp is skipped for token-denominated rows (fx_rate remains valid) — see stampMainCurrencyFx.

Wallet top-up (verified)

initiateCreditTopupPayment (app/_actions/wallet.ts) → WalletConductor.initiateTopUp → purpose wallet_topup → webhook wallet-topup*.ts → creditBalanceService.addFiatUsd (1:1 points). Distinct from native_token spend and from confidential native_token_onramp.

Public pool jar (verified)

POST /api/public-pools/[slug]/card-checkout → public_pool_contribution → desk FX → settlePublicPoolCardContribution. Native SPL chip-ins stay on contributeToPool (not Conductor).

Membership PayPal (verified)

POST /api/membership/payment/paypal → SubscriptionConductor provider paypal: recurring → Subscriptions v1 lifecycle webhooks; one-shot → Conductor Orders capture → recordPaidSubscription. UI: components/membership/payment-modal.tsx when public PayPal flag is on.

Ledger

data/migrations/004_payment_transactions.sql. Rows via DatabaseService / payment transaction service — result contract { success, data, error }.

Deep-dive: CheckoutRedirect DTO, dispatcher sequences, and API route map.

1. 1

   Pick default card processor

   Set PAYMENT_DEFAULT_PROCESSOR=wayforpay (UA/UAH-first) or stripe (USD-first). Optional purpose overrides: PAYMENT_STORE_PROCESSOR, PAYMENT_MEMBERSHIP_PROCESSOR, PAYMENT_NEWS_PROCESSOR, PAYMENT_WALLET_TOPUP_PROCESSOR, PAYMENT_NATIVE_TOKEN_ONRAMP_PROCESSOR, PAYMENT_PUBLIC_POOL_CONTRIBUTION_PROCESSOR (blank → default).

2. 2

   Enable gateways and rails in config

   In ring-config.json, set payment.cardPaymentProcessor, payment.supportedMethods, and payment.gateways.*.enabled. Fee % / feeFixedCents there are clone config defaults for display/estimation — not a guarantee of the PSP’s live schedule.

3. 3

   Wire credentials

   From env.local.template: WAYFORPAY_MERCHANT_ACCOUNT + WAYFORPAY_SECRET_KEY (+ WAYFORPAY_MERCHANT_PASSWORD for recurring/regularApi); or STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET; for PayPal PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET / PAYPAL_WEBHOOK_ID (+ membership plan ids when using Subscriptions). There is no WAYFORPAY_MERCHANT_ID.

4. 4

   Register canonical webhooks

   Point each PSP dashboard to:

   Endpoint	Provider verify
   POST /api/payments/wayforpay/webhook	WayForPay HMAC → dispatchWayForPayWebhook
   POST /api/payments/stripe/webhook	STRIPE_WEBHOOK_SECRET → dispatchStripeWebhook
   POST /api/payments/paypal/webhook	Transmission signature + PAYPAL_WEBHOOK_ID → dispatchPayPalWebhook

   Apply data/migrations/004_payment_transactions.sql before production ledger use.

5. 5

   Smoke checkout handoff

   Create a checkout through Conductor; UI must call followCheckoutResult / followCheckoutRedirect. Expect navigate (Stripe/PayPal/invoice URL) or form_post (WayForPay HPP). Confirm ledger row → handler fulfillment after webhook (or sync mark-paid for credit/token).

Quick setup sketch

PaymentProcessorId: wayforpay | stripe | paypal | credit_balance | native_token.

Webhook ingress (verified)

Store routes (verified)

Native token — checkout, idempotency, refunds (verified)

Store checkout UI. The token rail is enabled in features/store/components/checkout/payment-step.tsx via getClientStorePaymentRails(): NEXT_PUBLIC_PAYMENT_STORE_ALLOW_TOKEN === 'true' and payment.gateways.native_token.enabled !== false. Server-side gate stays isRailEnabled('store_order','native_token') (PAYMENT_STORE_ALLOW_TOKEN=true). The checkout flow posts placeAndPayStoreOrder (server action) or POST /api/store/payments/token — both route through PaymentConductor.createCheckout({ purpose: 'store_order', rail: 'native_token' }) → createNativeTokenCheckout (balance check → treasury SPL transfer → payment_transactions createPending → markPaid).

Membership native pay. POST /api/membership/payment/token is the single chokepoint (UI: components/membership/ring-payment-modal.tsx). Gate: isRailEnabled('membership_upgrade','native_token') reads isPaymentMethodEnabled('native_token') (payment.supportedMethods SSOT) — not the store flag, so membership native works with PAYMENT_STORE_ALLOW_TOKEN unset. Composition (ledger parity with card):

Idempotency contract (same as desk orders / NFT listings / public-pool contributions). Clients generate one UUID per payment intent (crypto.randomUUID() in checkout-client.tsx / ring-payment-modal.tsx) and reuse it on retry. payment_transactions rows carry a top-level idempotency_key; before charging, findByIdempotencyKey(userId, purpose, key) replays a paid row (same txHash, zero treasury movement) or returns 409 IDEMPOTENCY_IN_FLIGHT for an in-flight row. Old clients without a key keep the previous behavior.

Native refunds. POST /api/admin/payments/[orderReference]/refund — platform admin (any native payment) or vendor who owns the store order (order vendorSettlements ∩ getVendorEntities). Idempotent by orderReference (already-refunded replays refundTxHash); full-amount only; treasury→user via transferTokenFromTreasury; ledger gets status refunded + refundTxHash in processor_payload. Transfer failure keeps the row paid (retryable). Minimal scope — no subscription_ledger / order-status flip.

Ledger precision. Native-token rows store amount_minor in token precision (tokenAmount × 1e6, currency = token symbol); the main-currency stamp is skipped for token-denominated rows (fx_rate remains valid) — see stampMainCurrencyFx.

Wallet top-up (verified)

initiateCreditTopupPayment (app/_actions/wallet.ts) → WalletConductor.initiateTopUp → purpose wallet_topup → webhook wallet-topup*.ts → creditBalanceService.addFiatUsd (1:1 points). Distinct from native_token spend and from confidential native_token_onramp.

Public pool jar (verified)

POST /api/public-pools/[slug]/card-checkout → public_pool_contribution → desk FX → settlePublicPoolCardContribution. Native SPL chip-ins stay on contributeToPool (not Conductor).

Membership PayPal (verified)

POST /api/membership/payment/paypal → SubscriptionConductor provider paypal: recurring → Subscriptions v1 lifecycle webhooks; one-shot → Conductor Orders capture → recordPaidSubscription. UI: components/membership/payment-modal.tsx when public PayPal flag is on.

Ledger

data/migrations/004_payment_transactions.sql. Rows via DatabaseService / payment transaction service — result contract { success, data, error }.

Deep-dive: CheckoutRedirect DTO, dispatcher sequences, and API route map.