# Integrations

Source: https://caravelpay.app/docs/integrations · Caravel Pay docs · Last updated 2026-11-10

Install Caravel Pay on your billing or shop platform: upload the module, paste your Polygon wallet and save. Every module creates its API keys for you, sends buyers to the hosted checkout, and marks invoices paid only after confirming the payment with the API.

## Choose your platform

| Platform | Requires | Download |
|---|---|---|
| [**WooCommerce**](https://caravelpay.app/docs/woocommerce) | WordPress + WooCommerce, HTTPS | [`caravel-pay-woocommerce.zip`](https://caravelpay.app/download/caravel-pay-woocommerce.zip) |
| [**WHMCS**](https://caravelpay.app/docs/integrations#whmcs) | WHMCS 8, HTTPS System URL | [`caravel-pay-whmcs.zip`](https://caravelpay.app/download/caravel-pay-whmcs.zip) |
| [**Easy Digital Downloads**](https://caravelpay.app/docs/integrations#edd) | EDD 3.x, WordPress 6.2+, store currency USD | [`caravel-pay-edd.zip`](https://caravelpay.app/download/caravel-pay-edd.zip) |
| [**FOSSBilling**](https://caravelpay.app/docs/integrations#fossbilling) | FOSSBilling 0.7.2+, invoices in USD | [`caravel-pay-fossbilling.zip`](https://caravelpay.app/download/caravel-pay-fossbilling.zip) |
| [**Paymenter**](https://caravelpay.app/docs/integrations#paymenter) | Paymenter 1.x, invoices in USD | [`caravel-pay-paymenter.zip`](https://caravelpay.app/download/caravel-pay-paymenter.zip) |
| [**PrestaShop**](https://caravelpay.app/docs/integrations#prestashop) | PrestaShop 1.7.7 to 8.x, PHP 7.4+, store currency USD | [`caravel-pay-prestashop.zip`](https://caravelpay.app/download/caravel-pay-prestashop.zip) |
| [**OpenCart**](https://caravelpay.app/docs/integrations#opencart) | OpenCart 4.0.2+, customer currency USD | [`caravelpay.ocmod.zip`](https://caravelpay.app/download/caravelpay.ocmod.zip) |
| [**Magento 2**](https://caravelpay.app/docs/integrations#magento) | Magento / Adobe Commerce 2.4.4+ or Mage-OS, Luma checkout, cron, orders in USD | [`caravel-pay-magento2.zip`](https://caravelpay.app/download/caravel-pay-magento2.zip) |
| [**Laravel**](https://caravelpay.app/docs/integrations#laravel) | Laravel 10 to 12, PHP 8.1+ | [`caravel-pay-laravel.zip`](https://caravelpay.app/download/caravel-pay-laravel.zip) |
| [**Blesta**](https://caravelpay.app/docs/integrations#blesta) | Blesta 5, invoices in USD | [`caravel-pay-blesta.zip`](https://caravelpay.app/download/caravel-pay-blesta.zip) |
| [**HostBill**](https://caravelpay.app/docs/integrations#hostbill) | HostBill, invoices in USD | [`caravel-pay-hostbill.zip`](https://caravelpay.app/download/caravel-pay-hostbill.zip) |
| [**Clientexec**](https://caravelpay.app/docs/integrations#clientexec) | Clientexec 7.3+, invoices in USD | [`caravel-pay-clientexec.zip`](https://caravelpay.app/download/caravel-pay-clientexec.zip) |
| [**Your own PHP code**](https://caravelpay.app/docs/php-sdk) | PHP 7.4+ | [`caravel-php-1.0.0.zip`](https://caravelpay.app/download/caravel-php-1.0.0.zip) |
| [**Your own Node.js code**](https://caravelpay.app/docs/node-sdk) | Node 18.17+ | [`caravel-pay-1.0.0.tgz`](https://caravelpay.app/download/caravel-pay-1.0.0.tgz) |
| [**No website**](https://caravelpay.app/docs/payment-links) | A Polygon wallet | Nothing to install |

## How every module works

- **No account, no keys to copy.** When you save your wallet (or, on platforms without a save hook, at the first payment), the module calls [POST /v1/connect](https://caravelpay.app/docs/connect) and stores the merchant id and secret on your server.
- **Invoice → checkout → redirect.** The checkout is created when the buyer clicks pay, not when an invoice is viewed or emailed. A second click reuses the open checkout.
- **Paid means confirmed.** Webhooks are verified, then the module re-reads the checkout with a signed [GET /v1/checkouts/{id}](https://caravelpay.app/docs/checkouts#retrieve). Only a confirmed `paid` records the payment, with the payout transaction hash as its id.
- **Only a confirmed `paid` marks an invoice paid.** `underpaid` and `review` leave the invoice unpaid and add a note. There is no tolerance setting to get wrong: Caravel Pay decides what counts as paid, which is at least 85% of the amount, to allow for the card provider's fee. See [Checkout statuses](https://caravelpay.app/docs/statuses).
- **Changing your wallet** creates new keys. Checkouts already started finish on the old wallet, and their webhooks keep verifying for 7 days.
- **US dollars.** Checkouts are priced in USD. WHMCS can convert other currencies for you; the other platforms need USD invoices.

> **There is no test mode.** Check your setup with a small real payment, such as a $1.00 invoice. The payout is what arrives after the card provider's fee, minus the 2% Caravel fee.

## WHMCS

A gateway module named `caravelpay` for WHMCS 8. The Caravel Pay PHP SDK is bundled, so there's no Composer step.

### Install

1. **Download and unzip** [`caravel-pay-whmcs.zip`](https://caravelpay.app/download/caravel-pay-whmcs.zip).
2. **Upload** its `modules/` folder into your WHMCS root, merging with the existing one. It adds `modules/gateways/caravelpay.php`, `modules/gateways/caravelpay/` and `modules/gateways/callback/caravelpay.php`.
3. **Activate** under **Setup › Payments › Payment Gateways › All Payment Gateways › Caravel Pay**.
4. **Paste your payout wallet** (and optionally a contact email) and click **Save Changes**. The settings page shows **Connected as mch\_…**.

Your System URL must be `https://`. For clients in other currencies, set **Convert To For Processing** to USD: the USD amount is charged and the invoice is credited in its own currency. The webhook endpoint `/modules/gateways/callback/caravelpay.php` must accept `POST` from the internet.

### How invoices update

| Checkout status | WHMCS |
|---|---|
| `paid` | `addInvoicePayment()` with the payout tx hash, the invoice amount and the 2% Caravel fee. Gateway Log: *Successful* |
| `underpaid` | Not paid. Gateway Log *Underpaid* and an invoice note with the amount that arrived |
| `review` | Not paid. Gateway Log *Review* and an invoice note |
| `expired` | Not paid. Gateway Log *Expired*. The client can click Pay Now again |

Every webhook outcome, including rejected signatures, is listed under **Billing › Gateway Log**. Renewal invoices are paid from the invoice like any other: there are no automatic charges.

### Switching from PayGate

The PayGate modules (`paygatedottohosted`, `paygatedottocustom`) can stay active while you switch. If one is configured, the Caravel Pay settings page shows the wallet it pays out to, so you can paste the same one. Nothing is copied automatically. Make Caravel Pay the default gateway. When you later deactivate PayGate, WHMCS asks which gateway its clients and invoices move to.

## Easy Digital Downloads

A WordPress plugin that adds Caravel Pay as an EDD 3.x payment gateway.

### Install

1. **Download** [`caravel-pay-edd.zip`](https://caravelpay.app/download/caravel-pay-edd.zip).
2. **Upload and activate** under **Plugins › Add New Plugin › Upload Plugin**.
3. **Paste your payout wallet** under **Downloads › Settings › Payments › Caravel Pay** and save. A notice confirms *Caravel Pay is connected*.
4. **Turn it on** under **Downloads › Settings › Payments › General › Active Gateways**.

### How orders update

| Checkout status | EDD order |
|---|---|
| `paid` | Complete. The transaction id is the payout tx hash, and a note gives the payout |
| `underpaid` `review` | On Hold (Pending if your EDD has no On Hold status), with a note |
| `expired` | Failed, with a note. A payment found later still completes the order |

The purchase confirmation page also checks a pending order with one signed request, so buyers usually see *Complete* straight away. Allow `POST` to `/wp-json/caravel-pay-edd/v1/webhook` in your security plugin or firewall.

### Switching from PayGate

If PayGate's EDD gateway is configured, the Caravel Pay settings show the wallet it pays out to, so you can paste the same one. Both gateways can stay active while you test. Then untick PayGate under Active Gateways.

## FOSSBilling

A payment adapter for FOSSBilling 0.7.2 and later.

### Install

1. **Download and unzip** [`caravel-pay-fossbilling.zip`](https://caravelpay.app/download/caravel-pay-fossbilling.zip) in your FOSSBilling root. It adds `library/Payment/Adapter/CaravelPay/`.
2. **Install the gateway**: in the admin area, open **Payment gateways**, choose the **New payment gateway** tab and install **CaravelPay**.
3. **Paste your payout wallet**, tick **Enabled** and save. The adapter connects to Caravel Pay at the first payment.

### How invoices update

On `paid`, the amount is added to the client's balance and the invoice is paid with credits, the way FOSSBilling's own gateways do it. The transaction gets the payout tx hash as its id. `underpaid` and `review` add an invoice note and leave the invoice unpaid. FOSSBilling's `ipn.php` normally answers `200` even when an adapter fails, so this adapter sets the HTTP status itself, which makes Caravel Pay retry failed deliveries.

### Switching from PayGate

Install Caravel Pay next to PayGate's adapter, paste the same Polygon wallet, and disable PayGate once its open invoices are settled.

## Paymenter

A gateway extension for Paymenter 1.x.

### Install

1. **Download** [`caravel-pay-paymenter.zip`](https://caravelpay.app/download/caravel-pay-paymenter.zip). It contains one folder, `CaravelPay/`.
2. **Put the folder** in `extensions/Gateways/`, giving `extensions/Gateways/CaravelPay/CaravelPay.php`. Or upload the zip, if your Paymenter version can upload extensions from the admin area.
3. **Add a gateway** in the admin area, choose **Caravel Pay**, paste your payout wallet and save. Saving connects to Caravel Pay.

### How invoices update

Caravel Pay is offered for USD invoices only. On `paid`, the module calls `ExtensionHelper::addPayment()` with the remaining amount, the 2% Caravel fee and the payout tx hash; a repeat with the same tx hash updates that transaction instead of adding one. `underpaid` and `review` leave the invoice unpaid and are logged as warnings in the Laravel log. `APP_URL` must be your public HTTPS address, and `POST /extensions/caravelpay/webhook` must be reachable.

### Switching from PayGate

Add the Caravel Pay gateway with the same Polygon wallet you used with PayGate, then disable PayGate once its open invoices are settled.

## PrestaShop

A payment module named `caravelpay` for PrestaShop 1.7.7 to 8.x. The Caravel Pay PHP SDK is bundled, so there's no Composer step. It needs PHP 7.4 or later; PrestaShop 1.7.7 itself stops at PHP 7.3, so 1.7.8 is the practical minimum.

### Install

1. **Upload** [`caravel-pay-prestashop.zip`](https://caravelpay.app/download/caravel-pay-prestashop.zip) under **Modules › Module Manager › Upload a module**.
2. **Configure** the module: paste your payout wallet and click **Save**. The status panel shows **Connected** with your merchant id.
3. **Enable it for US dollar** (and your carriers, groups and countries) under **Payment › Preferences**.

The webhook URL is `/module/caravelpay/webhook` (or `index.php?fc=module&module=caravelpay&controller=webhook` without friendly URLs). It must accept `POST` from the internet, so keep maintenance mode off.

### How orders update

Placing the order creates it in **Awaiting Caravel Pay payment** and sends the buyer to the hosted checkout.

| Checkout status | PrestaShop order |
|---|---|
| `awaiting_payment` `confirming` | Awaiting Caravel Pay payment |
| `paid` | **Payment accepted**. The payment is recorded with the payout tx hash as its transaction id, and a private note shows the payout. |
| `underpaid` `review` | **Caravel Pay: on hold**, with a private note |
| `expired` | **Canceled** if still awaiting. A late `paid` still moves it to Payment accepted. |

While an order is unpaid, the confirmation page and the customer's order page show a **Pay now** button.

### Switching from PayGate

Install Caravel Pay next to the PayGate module (`instantpayment_gateway`) and copy your wallet across; nothing is imported automatically. PayGate's *Awaiting card payment* corresponds to *Awaiting Caravel Pay payment*, and its below-tolerance *Payment error* to *Caravel Pay: on hold*. There is no fees-tolerance setting. Disable PayGate under **Payment › Preferences** once its open orders are settled.

## OpenCart

An OpenCart 4 payment extension (4.0.2.0 or later). OpenCart 3 isn't supported. **Keep the file name `caravelpay.ocmod.zip`**, because OpenCart 4 names the extension after it.

### Install

1. **Upload** [`caravelpay.ocmod.zip`](https://caravelpay.app/download/caravelpay.ocmod.zip) under **Extensions › Installer** and click **Install** next to it.
2. **Install the payment method** under **Extensions › Extensions › Payments**, then edit it.
3. **Paste your payout wallet**, switch Status on and save. The Connection panel shows **Connected**.

Caravel Pay shows at checkout only when the customer's currency is USD. The webhook URL is `index.php?route=extension/caravelpay/payment/caravelpay.callback`.

### How orders update

| Checkout status | OpenCart order (statuses are configurable) |
|---|---|
| `awaiting_payment` `confirming` | Pending |
| `paid` | **Processing**. The customer is notified, and the history comment shows the payout and its transaction link. |
| `underpaid` `review` | **On Hold** (created at install), with a comment |
| `expired` | **Canceled** if still pending. A late `paid` still moves it to Processing. |

### Switching from PayGate

Install Caravel Pay next to the PayGate extension (`paygatedotto`) and copy your wallet across. PayGate's paid-order status maps to **Paid status**; there is no Fees Tolerance or API Domain setting. Switch PayGate off once its open orders are settled.

## Magento 2

A module named `Caravel_Pay` for Magento Open Source and Adobe Commerce 2.4.4 or later, and Mage-OS. It supports the Luma checkout; Hyvä Checkout needs its own renderer, which isn't included. Magento cron must run.

### Install

1. **Add the module**: either install [`caravel-pay-magento2-composer.zip`](https://caravelpay.app/download/caravel-pay-magento2-composer.zip) as a Composer artifact (`composer config repositories.caravelpay artifact ./artifacts`, then `composer require caravelpay/module-caravel-pay:1.0.0`), or unzip [`caravel-pay-magento2.zip`](https://caravelpay.app/download/caravel-pay-magento2.zip) in the Magento root (it creates `app/code/Caravel/Pay`).
2. **Run** `bin/magento module:enable Caravel_Pay` and `bin/magento setup:upgrade`. In production mode, also run `setup:di:compile` and `setup:static-content:deploy`.
3. **Configure** under **Stores › Configuration › Sales › Payment Methods › Caravel Pay**: enable it, paste your payout wallet and save. The Connection line shows **Connected**.

### How orders update

Place Order creates the order as Pending Payment with the status **Awaiting Caravel Pay payment**. Magento's own "Pending Payment Order Lifetime" cleanup doesn't cancel orders in this status.

| Checkout status | Magento order |
|---|---|
| `awaiting_payment` `confirming` | Awaiting Caravel Pay payment |
| `paid` | **Invoiced** (transaction id = payout tx hash), then Processing. The order email is sent now. |
| `underpaid` `review` | **On Hold**, with a comment |
| `expired` | A comment. Cron cancels the order after *Cancel unpaid orders after (hours)* (default 24), once it has re-checked that the checkout is still expired. |

Cancellation waits because Magento can't invoice a cancelled order, and a payment sent just before expiry can still confirm after it. If a payment arrives after the order was cancelled, the order stays cancelled and gets a comment with the payout, so you can fulfil a replacement or refund from your wallet.

### Switching from PayGate

Install Caravel Pay next to the PayGate module and copy your wallet across. PayGate's hosted method corresponds to Caravel Pay; its single-provider method has no equivalent. PayGate's own order status and its 24-hour cron cancellation correspond to *Awaiting Caravel Pay payment* and *Cancel unpaid orders after (hours)*. A short payment goes On Hold in both. Disable PayGate once its open orders are settled.

## Laravel

A package for Laravel 10, 11 and 12 (PHP 8.1+): the `Caravel` facade, a signed webhook route with the `caravel.webhook` middleware, and events for the checkout's re-fetched status.

### Install

1. **Require it** from the zip as a Composer artifact: put [`caravel-pay-laravel.zip`](https://caravelpay.app/download/caravel-pay-laravel.zip) in an `artifacts/` folder in your project, run `composer config repositories.caravelpay artifact ./artifacts`, then `composer require caravelpay/caravel-laravel:1.0.0`.
2. **Get your keys**: `php artisan caravel:connect 0xYourWallet --site=https://shop.example` prints `CARAVEL_MERCHANT_ID` and `CARAVEL_SECRET` for `.env`. The secret is shown only once.
3. **Create checkouts** with `Caravel::createCheckout([...])` and `callback_url` set to `route('caravel.webhook')`.

### How orders update

The route verifies the signature, answers duplicates with 200, re-reads the checkout and dispatches `CheckoutPaid`, `CheckoutUnderpaid`, `CheckoutExpired` or `CheckoutReview` for its current status. Your listeners update the order. If a listener throws, the route answers 503 and Caravel Pay retries. To rotate keys, run `caravel:connect --force` and keep the printed `CARAVEL_PREVIOUS_CREDENTIALS` line for a day.

### Switching from PayGate

The `caravel.webhook` middleware takes the place of PayGate's `paygate.callback`. The callback is a signed `POST` with a fixed amount, so there's no order token or tolerance to check. Both packages can run side by side while open PayGate payments finish.

## Blesta

A non-merchant gateway for Blesta 5.

### Install

1. **Unzip** [`caravel-pay-blesta.zip`](https://caravelpay.app/download/caravel-pay-blesta.zip) in the Blesta root. It adds `components/gateways/nonmerchant/caravel_pay/`.
2. **Install** Caravel Pay under **Settings › Company › Payment Gateways › Available**.
3. **Paste your payout wallet** and click **Update Settings**. Saving connects; if connecting fails, the reason is shown and nothing is saved.

### How invoices update

On `paid`, an **Approved** transaction is applied to the invoices that were paid. Its transaction id is the checkout id and its reference id the payout tx hash. `underpaid`, `review` and `confirming` record a **Pending** transaction that isn't applied; the same transaction becomes Approved if the checkout is paid later. `expired` records nothing.

### Switching from PayGate

PayGate has no Blesta gateway, so there's nothing to migrate: install Caravel Pay and enable it.

## HostBill

A payment module for HostBill. HostBill is the one exception to "no keys to copy": its module settings can't connect by themselves, so you get the merchant id and secret once with the bundled helper.

### Install

1. **Unzip** [`caravel-pay-hostbill.zip`](https://caravelpay.app/download/caravel-pay-hostbill.zip) in the HostBill root. It adds `includes/modules/Payment/caravelpay/`.
2. **Get your keys** on the server: `php includes/modules/Payment/caravelpay/lib/caravel-connector/connect-cli.php --wallet=0x… --site=https://billing.example --platform=hostbill`. The secret is shown only once.
3. **Activate** Caravel Pay under **Settings › Modules › Payment Modules** and paste the Merchant ID and Secret.

### How invoices update

The invoice page links to a signed start URL, so the amount can't be changed. On `paid`, a transaction for the checkout amount is added to the invoice once, with the checkout id as its transaction id and the payout link in its description. Every other status is only written to the gateway log. When you replace the keys, list the old pair under *Previous credentials* for a day.

### Switching from PayGate

PayGate has no HostBill module. HostBill's built-in "Paygate" gateway appears to belong to an unrelated provider, so there's nothing to migrate.

## Clientexec

An offsite gateway plugin for Clientexec 7.3 or later.

### Install

1. **Upload** the `caravelpay` folder from [`caravel-pay-clientexec.zip`](https://caravelpay.app/download/caravel-pay-clientexec.zip) into `plugins/gateways/`.
2. **Open** **Settings › Plugins › Gateways › Caravel Pay**, paste your payout wallet and turn on One-Time Payments.

The plugin connects at the first payment and keeps its keys in its own table, with the secret encrypted. To get new keys for the same wallet, change *Reconnect Code*.

### How invoices update

On `paid`, the plugin records **Payment accepted** for the checkout amount, once. The transaction id is the checkout id, and the description carries the payout link; Clientexec handles partial payments and overpayments as usual. `underpaid` and `review` record **Payment pending** with the amount that arrived. `expired` logs a rejected attempt without changing the invoice.

### Switching from PayGate

PayGate has no Clientexec gateway, so there's nothing to migrate.

## Postman and AI agents

Two files for developers. [`caravel-pay-api.postman_collection.json`](https://caravelpay.app/download/caravel-pay-api.postman_collection.json) holds every API request. Its pre-request script signs each one for you, and a "signed test webhook" request lets you test your own handler. [`caravel-pay-api-llm.md`](https://caravelpay.app/download/caravel-pay-api-llm.md) is a single reference for AI coding agents: the rules an integration must follow, the signing code in Node.js, PHP, Python and curl, every endpoint and error, and the test vectors.

## Your own code

Building on another platform? The [PHP SDK](https://caravelpay.app/docs/php-sdk) and [Node.js SDK](https://caravelpay.app/docs/node-sdk) do the signing, webhook verification and response checks for you. Each module above is built on the PHP SDK. Or call the [API](https://caravelpay.app/docs/checkouts) directly.