Get started

WooCommerce plugin

Accept card, Apple Pay and Google Pay in a WooCommerce store and receive USDC on Polygon. Install the plugin, paste your wallet, place a test order.

Requirements#

A self-hosted WordPress site with WooCommerce, served over HTTPS.
Store currency set to US dollar (USD). Checkouts are priced in USD in this version.
A Polygon address you control, for payouts.

Install#

Download the plugin. Get the latest caravel-pay-woocommerce.zip.

Available at launch
Upload it. In WordPress, go to Plugins › Add New Plugin › Upload Plugin, choose the zip file and click Install Now.
Activate. Click Activate Plugin. Caravel Pay now appears in your payment methods.

Paste your wallet#

Go to WooCommerce › Settings › Payments › Caravel Pay and fill in the settings below, then click Save changes.

Setting	What to enter
Enable	Turn on to show Caravel Pay at checkout.
Payout wallet	Your Polygon address, starting with `0x`. Every payout is sent here.
Title	What buyers see at checkout. Default: Card, Apple Pay or Google Pay.
Description	Optional short line under the title.

Saving connects your store to Caravel Pay, and the settings page shows Connected. The plugin keeps its API credentials for you, so there is nothing else to copy.

Behind the scenes the plugin makes the call described in Get your API keys and stores the merchant id and secret where only your server can read them.

Check the address twice. Payouts are on-chain transfers and can't be reversed. If you use an exchange deposit address, make sure that exchange accepts USDC on the Polygon network.

Change your wallet#

Paste the new address and save. The plugin gets new keys for it: new orders pay out to the new wallet, and orders already started finish on the old one. The Reconnect button gets new keys for your current wallet, for example if the old ones stopped working.

Moving from the PayGate plugin#

If the PayGate plugin is installed, the settings page shows Import from PayGate plugin. It copies your PayGate checkout title, description and icon into Caravel Pay, and lists the payout wallet saved in PayGate with a Use this wallet button that fills in the field for you. Check it, then save. The PayGate plugin and its settings are only read, never changed, so both can run side by side while you switch. An imported icon shows as an Icon setting, with an option to go back to the default.

Place a test order#

Create a cheap product, for example a private $1.00 item, so the test costs little.
Check out as a buyer in a private browser window and choose Caravel Pay. You are sent to the hosted checkout.
Pay with a card, Apple Pay or Google Pay. The card provider's fee is shown before you confirm.
Watch the order. You return to the order-received page. When the checkout.paid webhook arrives, the order moves to Processing and an order note records the payout and its transaction hash.
Check your wallet. The USDC arrives at your payout address on Polygon.

How orders update#

The plugin listens for webhooks and moves orders for you:

Checkout status	WooCommerce order
awaiting_payment confirming	Pending payment
paid	Processing (or Completed, for orders WooCommerce treats as virtual and downloadable), with a note showing the payout and transaction hash
underpaid	On hold, with a note showing how much arrived
review	On hold, with a note
expired	Cancelled, if the order is still on Pending payment. An order already On hold (for example underpaid) stays on hold, with a note.

Rarely, a payment sent just before a checkout expired confirms after it. The plugin then completes the cancelled order as paid (Processing or Completed), with a note, so ship it as normal. A payment sent after expiry goes to review and puts the order on hold.

Every checkout carries the WooCommerce order ID plus a short random suffix as its order_id, for example 1042-k7Pq2x. If a buyer tries again after a checkout expired, the next one ends in -2. Both stay linked to the same order.

See Checkout statuses for what each one means.

Troubleshooting#

An order stays on Pending payment after paying#

The webhook probably isn't reaching your store. Check that:

a security plugin, firewall or CDN rule isn't blocking POST requests from outside your site;
the site isn't in maintenance mode or behind a password;
your page cache doesn't cache the plugin's callback URL, /wp-json/caravel-pay/v1/webhook (or /index.php?rest_route=/caravel-pay/v1/webhook if your permalinks are set to Plain).

The plugin logs every webhook it receives under WooCommerce › Status › Logs (source caravel-pay). Webhooks are retried for up to 24 hours, so an order updates on its own once the block is fixed.

The settings page says Not connected#

The message under the status says what went wrong. Usually it is one of these:

your server can't make outgoing HTTPS requests to api.caravelpay.app;
the payout wallet was refused: use an ordinary Polygon wallet you control, not a contract or token address;
too many attempts in a short time: wait a few minutes.

Then click Reconnect.

Caravel Pay doesn't show at checkout#

Make sure Enable is on, a payout wallet is saved and the status is Connected. Caravel Pay is also hidden while the status is Paused (the reason is shown under it; open checkouts and payouts still finish) or Waiting for approval.
Check the store currency is USD under WooCommerce › Settings › General.

Still stuck? Email hello@caravelpay.app with your store URL and the order number.