Checkout Module
Shared payment flow used by ICO, Crypto Sales and Shop — PayPal, Stripe, crypto balance and Web3/MetaMask in one place
What the Checkout Module Is
The checkout module is the single payment surface every other module hands off to. When a user clicks "Buy" on an ICO page, a shop product or a crypto sale, the originating module creates a pending order and sends the user to the checkout page. The checkout shortcode loads the order, presents the payment options enabled in General Settings, and on success marks the order completed.
📋 Quick facts
- Two shortcodes:
[wpcrypto_checkout_page]and[wpcrypto_success_page] - Four payment methods: PayPal, Stripe, crypto balance, Web3 / MetaMask
- Two-step order lifecycle: orders are pending until paid, then marked completed
- Gateway credentials: safely stored from the General Settings screen
Two Shortcodes
| Shortcode | Place it on | What it does |
|---|---|---|
[wpcrypto_checkout_page] |
Your checkout page | Reads the order via ?checkout=… and renders the payment chooser + payment forms for whatever gateways you have enabled. |
[wpcrypto_success_page] |
Your success page | Reads the order via ?checkout=… and renders the confirmation receipt and deliverable (shop download URL, ICO tokens credited, crypto balance update, etc.). |
Create one WordPress page for each shortcode and configure the page URLs in General Settings → Platform URLs so the modules redirect to the right place.
The Four Payment Methods
The checkout chooser only shows gateways with credentials saved in General Settings. Disable any gateway by clearing its credentials.
| Method | How it works |
|---|---|
| PayPal | The PayPal SDK is enqueued client-side using your saved client id; the user pays via the PayPal Smart Buttons. Sandbox or live environment is selected from a setting. |
| Stripe | Stripe.js is enqueued client-side; the user pays with card / Apple Pay / Google Pay. Sandbox or live environment is selected from a setting. |
| Crypto balance | The order total is deducted from the user's internal balance (denominated in the order's quote currency). A balance-before / balance-after snapshot is written to the transaction record. |
| Web3 / MetaMask | The user signs and sends an on-chain transfer from their own wallet to one of your configured deposit addresses. The plugin verifies the transaction hash before completing the order. |
Web3 Networks
The Web3 / MetaMask option is not hard-coded to "Ethereum + BSC + Polygon + custom" — it is built dynamically from your Coins Manager. For every coin you have:
- marked
payment_enabled = true, and - given an active network with a deposit address
the checkout shows that coin / network as a Web3 payment option. In practice this means the user sees a network picker matching your enabled list (typically Bitcoin, Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, Base, Linea, TRON — the chains you configured for payments).
Order Lifecycle
The checkout module uses the same shared order lifecycle as the other purchase modules:
| Status | When it is set |
|---|---|
PENDING | Default on insert (the originating module — ICO, shop, buy-crypto — sets this when it hands off to checkout). |
COMPLETED | Set after payment is confirmed (or, for shop orders, after an admin approval). The deliverable is released on the success page. |
The plugin does not write intermediate states like "Processing", "Cancelled" or "Failed" — failed payments leave the order in PENDING until the user retries or you remove it.
Product Types
The originating module records itself in the product_type column. The values you will see are the post-type slugs:
| product_type | Originating module |
|---|---|
crypto_purchase | Buy Crypto Module |
ico-page | ICO / Presale Module |
wpcrypto_shop | Smart Shop Module |
The success page uses this value to decide what receipt + deliverable to render.
What Gets Recorded on the Order
Beyond the status, the checkout flow writes the gateway response into the order row. The most useful fields:
- payment_method / payment_type / currency — what the user picked
- create_payment_request / create_payment_response — the initial gateway call payload + reply
- capture_payment_request / capture_payment_response — the capture call payload + reply (PayPal / Stripe)
- payment_transaction_id — the gateway-side id for reconciliation
- previous_balance / new_balance — for crypto-balance payments, the before/after snapshot
- discount_rate / discount_amount / used_coupon_code — if a coupon was applied
- completed_date / completed_at — when the order flipped to COMPLETED
Notifications
When an order is completed, the checkout module fires the platform notification hooks. Depending on what you have wired up in General Settings, this can produce:
- An email to the buyer with the receipt
- An email to the admin (if "notify admin on sale" is on)
- A Telegram alert to the admin bot (if a Telegram bot is configured)
Disable any channel by emptying its credentials.
Operator Notes
⚠️ Things to know
- Use HTTPS. Both PayPal Smart Buttons and Stripe Elements require HTTPS; the checkout will not work over plain HTTP.
- Set the platform URLs. General Settings → Platform URLs configures the checkout and success page URLs the modules redirect to.
- Sandbox vs live. Each gateway has a sandbox/live toggle in General Settings — get end-to-end tests passing in sandbox before flipping the switch.
- Web3 success depends on confirmations. The plugin waits for the tx hash to be confirmed before completing the order; faster chains complete in seconds, Bitcoin can take 10+ minutes.
Troubleshooting
"Order not found" on the checkout page
The confirmation code in the URL does not match an existing order. Confirm the originating module is redirecting properly and the URL has not been edited or stripped.
PayPal button does not appear
Either the PayPal credentials in General Settings are empty (gateway is hidden), or the page is being served over HTTP. Save credentials, switch to HTTPS, hard-refresh.
Stripe declines a real card
You may still be in sandbox. Verify the Stripe environment setting is set to live and the saved key starts with pk_live_.
Order stays PENDING after a successful Web3 transfer
The tx hash is still waiting for confirmations. Wait one block depth on the relevant chain. If it remains PENDING for an hour, paste the tx hash into a chain explorer to verify it actually went to one of your configured deposit addresses.