UlasendUlasendDocs
WooCommerce

WooCommerce integration

Install the Ulasend payment gateway in a test WordPress store.

Version 0.1.0 is a development preview for one-time USD orders using hosted USDC on Base checkout. It supports classic checkout and Checkout Blocks, and HPOS order storage. Subscriptions, saved cards, bank-transfer checkout, automatic refunds, and non-USD orders are not supported.

Install the plugin

Use PHP 8.1 or later, WordPress 6.6 or later, and WooCommerce 9 or later. Checkout requires MySQL or MariaDB with named-lock support. SQLite is supported only by the source repository's isolated test fixture. Use HTTPS for live checkout and for externally delivered webhooks.

  1. Use a staging or local WordPress installation with WooCommerce.
  2. Download Ulasend Payments 0.1.0.
  3. In WordPress, open Plugins → Add New → Upload Plugin. Select the ZIP, install it, and activate it.
  4. Open WooCommerce → Settings → Payments → Ulasend and start with test mode.

Connect your Ulasend account

Copy your merchant ID from Integrations. In Developers, create a test API key with invoices:writepermission, which also permits reads, and copy it into the plugin's test settings. Keep the live key in its separate field. Keys stay on your WordPress server and must not be added to a page, theme, or browser script.

Your Ulasend merchant account must be approved for payment processing, with USDC on Base enabled under accepted coins. Follow the account setup guide if processing is not yet available.

Configure a matching Ulasend webhook endpoint using the URL shown by the plugin, then save the endpoint's signing secret in the matching mode's plugin settings. Verify the endpoint in Ulasend after saving the secret, then save the gateway as enabled in Test mode. Select invoice.paid, invoice.overpaid, invoice.partially_paid, invoice.expired, and invoice.manual_review, or select all events. Cancellation status is checked during reconciliation; there is no separate cancellation webhook event.

Test: https://your-store.example/wp-json/ulasend/v1/webhook/test
Live: https://your-store.example/wp-json/ulasend/v1/webhook/live

Ulasend cannot deliver webhooks to a private localhost URL. For fully local tests, use the mock payment tests in the source repository; they are excluded from the downloadable plugin ZIP. A staging integration needs a publicly reachable HTTPS endpoint. Creating and verifying live endpoints requires an owner/admin session with two-factor authentication.

Test an order

  1. Keep the plugin in test mode and sign in as a store manager for a test purchase.
  2. Create a USD order and choose Ulasend at checkout.
  3. Confirm that Ulasend displays test mode before simulating payment.
  4. Check the order notes and saved invoice reference. A verified test payment stays On hold, moves no money, and does not release the order for fulfillment.
  5. Repeat notifications, retry checkout, and test a partial or cancelled payment. They must not create duplicate fulfillment.

Test checkout is visible only to signed-in users who can manage WooCommerce. Use staging inventory and email settings, since your other extensions may still act on an On hold order.

Order updates and recovery

The plugin uses signed notifications and server-side invoice checks to reconcile the order. It checks the saved invoice, reference, mode, USD total and full quote, including any passed processing fee. A browser return does not mark the order paid. Existing attempts retain their original mode for reconciliation when you change the plugin's default. A checkout retry in the changed mode is refused.

Use the order action Recheck Ulasend payment when a notification is delayed. Recovery is scheduled every five minutes for unresolved invoices created in the last 30 days; use the order action for older invoices. Configure reliable WordPress cron on a live store. Payments received after an order is cancelled or changed require review. Cancelling an order does not refund a transfer.

The plugin keeps one invoice attempt per order and does not replace an expired checkout. Retries reuse the original request. If a create request has an uncertain result and no saved invoice ID, creation retries stop after 23 hours. Contact Ulasend to reconcile it before creating a replacement order. Changed order totals also require review.

If the plugin flags a paid invoice after observing it expired or cancelled, review the order and return it to On hold if appropriate. Recheck the payment, then use the separate Accept verified late Ulasend payment order action to approve fulfillment. A routine recheck does not release this review hold.

To pause new checkouts, disable the gateway and keep its credentials so existing payments can still be reconciled. Disconnect clears credentials and pauses reconciliation until you restore them. Blank secret fields preserve saved values.

Before live use

Complete a staging checkout test with your actual WooCommerce extensions, stock settings, emails, and fulfillment tools. Then configure and verify the separate live webhook and enable the live gateway. Your Ulasend merchant account must be approved and ready to receive payments.