Advanced8 min read
Shopify Crypto Payment Bridge
Connect a Shopify custom manual payment method to PolyPay Hosted Checkout. This isn't a Shopify-approved Payments App.
Integration boundary
A native Shopify Payments App requires Payments Partner approval, restricted scopes, mTLS, and Shopify review. This bridge is for a merchant-owned Custom App and an explicitly configured manual payment method.
Deployment steps
- Deploy the PHP bridge and copy config.example.php to a private config.php
- Create a Shopify Custom App with read_orders and write_orders
- Create a manual method named exactly PolyPay - Crypto Payment
- Set its static payment instruction URL to https://your-payment-host/pay
- Configure Shopify JSON webhooks for order creation and cancellation
- Run php bin/activate.php and validate the entire flow with PolyPay Sandbox first
Payment and security rules
- Customers verify an order using its Shopify order number and order email
- PolyPay Hosted Checkout owns payment-method selection
- A browser return page never marks the Shopify order paid
- PolyPay callbacks require timestamp, nonce, and Ed25519 v2 verification
- Callbacks are deduplicated by environment and event_id
- Shopify cancellation synchronizes a still-pending PolyPay trade_id
- Orders currently need to be denominated in USD; refunds are manual
Horizontal scaling
The default nonce and event stores use a shared filesystem. Replace them with an atomic shared store such as Redis before running multiple application instances.