Get started

Integrations

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#

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 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}. Only a confirmed paid records the payment, with the payout transaction hash as its id.
• Short payments are never "paid". underpaid and review leave the invoice unpaid and add a note. There is no tolerance setting to get wrong. See Checkout 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.

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.

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#

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.

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#

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 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. 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 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.

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 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#

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 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 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.

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 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 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 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 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 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 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 and Node.js SDK do the signing, webhook verification and response checks for you. Each module above is built on the PHP SDK. Or call the API directly.