You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/docs/stripe-payment.md

2.8 KiB

Stripe Checkout payments

Virt Cloud uses Stripe-hosted Checkout for card and Alipay payments. Card data never enters the panel. A browser return is informational only; wallet and invoice settlement happens only after a verified Stripe Webhook event.

Database and encryption key

Fresh installs already include the Stripe tables in sql/ss.sql and the wider invoice-payment status contract in sql/cloud.sql. For an existing database, import sql/stripe_payment.sql once after its cloud schema is current. Before saving Stripe credentials, configure an independent 32-byte encryption key in the PHP runtime environment:

env[STRIPE_CREDENTIAL_KEY] = "generated-base64-value"

Generate a suitable value with:

php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'

Do not reuse the site data key or another payment driver's credential key. Changing this key without re-saving the Stripe credentials makes the stored ciphertexts unreadable.

Stripe Dashboard

  1. Open Admin -> Stripe payment and keep test mode enabled.
  2. Save a matching sk_test_... Secret key and the fixed HTTPS panel URL.
  3. In Stripe Workbench, create a Webhook endpoint at https://panel.example.com/stripe/webhook and subscribe to:
    • checkout.session.completed
    • checkout.session.async_payment_succeeded
    • checkout.session.async_payment_failed
    • checkout.session.expired
  4. Save the endpoint's whsec_... signing secret in the panel.
  5. Enable Alipay in Stripe Dashboard Payment methods when it is supported for the Stripe account's business country. The panel switch cannot grant a payment-method capability that Stripe has not enabled for the account.
  6. Test card and Alipay Checkout, Webhook delivery, wallet credit, invoice settlement and duplicate-event handling before switching to live mode.

Live mode requires a matching sk_live_... key and the live Webhook endpoint's own signing secret. Test and live Webhook signing secrets are not interchangeable.

Accounting and safety contract

  • The panel's wallet and cloud invoices are denominated in USD, so Stripe Checkout is fixed to usd. There is no implicit currency conversion.
  • Card and Alipay are separate panel methods and can be enabled independently.
  • Every Checkout Session is created with a stable Stripe idempotency key, but a request with an uncertain transport result is still fenced locally and is not automatically replayed.
  • Webhooks are verified against the exact raw request body and Stripe-Signature, limited to a five-minute timestamp tolerance and deduped by Stripe event ID.
  • Amount, currency, live/test mode, payment method, local order number, Checkout Session and PaymentIntent ownership are checked before settlement.
  • Stripe may retry failed Webhook deliveries. Replayed events cannot credit the wallet or settle an invoice twice.