# WooCommerce plugin

Source: https://caravelpay.app/docs/woocommerce.html · Caravel Pay docs · Last updated 2026-11-09

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

1. **Download the plugin.** Get the latest `caravel-pay-woocommerce.zip`.

   *Available at launch*

2. **Upload it.** In WordPress, go to **Plugins › Add New Plugin › Upload Plugin**, choose the zip file and click **Install Now**.

3. **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](https://caravelpay.app/docs/connect.html) 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

1. **Create a cheap product**, for example a private $1.00 item, so the test costs little.
2. **Check out as a buyer** in a private browser window and choose Caravel Pay. You are sent to the hosted checkout.
3. **Pay with a card**, Apple Pay or Google Pay. The card provider's fee is shown before you confirm.
4. **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.
5. **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](https://caravelpay.app/docs/statuses.html) 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](mailto:hello@caravelpay.app) with your store URL and the order number.