Guides
WooCommerce
Install and configure the payment gateway plugin.
Adds "Pay with Escrow (buyer protection)" as a payment method. The customer is sent to our hosted checkout; order status is updated automatically from webhooks.
Requirements
- WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (HPOS compatible)
- Store currency USD (the method hides itself otherwise)
- A seller account on Smart Contracts Escrow
- The site reachable over HTTPS from the internet (for webhooks)
Install
- Download the plugin (
.zip). - WordPress → Plugins → Add New → Upload Plugin → choose the zip → activate.
- WooCommerce → Settings → Payments → Smart Contracts Escrow → Manage.
Configure
| Setting | Value |
|---|---|
| API base URL | https://smartcontractsescrow.net/api/v1 |
| Secret API key | Seller dashboard → Integrations → Create key (sce_…) |
| Webhook signing secret | Add the URL shown under the field (https://your-store/wp-json/sce/v1/webhook) as an endpoint in the Integrations page, then paste its whsec_… secret |
| Debug log | Optional; logs to WooCommerce → Status → Logs (smart-contracts-escrow) |
Click Test next to the endpoint in the Integrations page — you should see a ping
delivery with status 200.
Order lifecycle
| Escrow event | WooCommerce order |
|---|---|
| Checkout placed | pending — customer redirected to escrow |
checkout.session.completed | on-hold (only if still pending) |
escrow.funded | payment_complete() → processing |
| You ship → order action "Escrow: mark as shipped / delivered" | Delivery submitted with tracking (reads _tracking_number / _tracking_provider; filter sce_wc_submission_details to customise) |
escrow.milestone.approved | Note |
escrow.completed | completed |
escrow.disputed / escrow.milestone.disputed | on-hold |
escrow.cancelled / escrow.expired / checkout.session.expired | cancelled if unpaid, otherwise a note for manual review |
Events are deduplicated per order (_sce_event_ids) and bound to the session the store
created (_sce_session_id), so two stores sharing a seller account cannot affect each
other's orders.
Known limitations
- No automatic refunds from WooCommerce — refunds happen through dispute resolution on the escrow platform.
- One milestone per order (the full amount). For deposits/staged delivery, create sessions
with
milestones[]from a custom integration. - Guest buyers must create an escrow account during checkout.
Testing checklist
- Place an order → redirected to
/checkout/<token>showing items, fees and total - Confirm & pay → order becomes Processing
- Run the "mark as shipped" order action → note "delivery submitted"
- Buyer approves in the escrow dashboard → order becomes Completed
- Let a session expire (or call
/expire) → unpaid order Cancelled - Tamper with a webhook body → endpoint returns
400 invalid signature