Guides

Blesta

A payment gateway for Blesta: clients pay invoices in bitcoin or USDC/USDT straight to your wallet, recorded by a signed webhook.

View as Markdown

The Perly Pay gateway adds crypto to your Blesta invoices. The client chooses Perly Pay under Pay or in the order form; on "Review and confirm" the gateway makes an invoice in Perly Pay for exactly the amount Blesta worked out, and Pay with crypto opens it. A signed webhook records the payment in Blesta. Blesta 6, or Blesta 5 on PHP 8.1 or later, with PHP's curl and json. Nothing to install with Composer: the PHP SDK is inside.

Perly Pay bills in USD or EUR, and the gateway says so to Blesta, so Blesta offers it only on payments in those two currencies.

Install

1
Get the gateway
Download perly-pay-blesta.zip from the latest release on GitHub.
2
Upload
Unzip it over your Blesta folder. It adds components/gateways/nonmerchant/perly_pay/.
3
Install
Settings → Company → Payment Gateways → Available, find Perly Pay and press Install. It makes one table, perly_pay_invoices.

Settings

Setting	What to put
Secret key	From Dashboard → Developers → API keys. `sk_test_…` for test mode, `sk_live_…` for real money. Full access, or Restricted with Webhook endpoints ticked: Test connection reads your webhooks.
Webhook signing secret	`whsec_…`, from the webhook you add for this Blesta (below). Until it is saved, clients see no button.
Payment page	Over the Blesta page (overlay) opens the checkout over Blesta's page. On pay.perly.io (redirect) sends the client to it. Phones always get the page itself.

1
Paste the key
Save, then press Test connection: it says whether the key works, its mode, and whether this Blesta's webhook is in Perly Pay.
2
Add the webhook
In Dashboard → Developers → Webhooks, add the address the settings show, https://your-blesta/callback/gw/1/perly_pay/ (1 is the company), with the invoice and refund events. Paste its secret and save.
3
Allow the overlay
For the overlay, add your Blesta address in Dashboard → Settings → Checkout → Sites that may embed the checkout.

Running several companies? Each has its own gateway, its own callback address (/callback/gw/<company id>/perly_pay/) and its own webhook in Perly Pay.

What clients pay with

The client picks a coin and network on the payment page and pays from any wallet. The money goes straight to yours.

Coin	Networks
BTC	Bitcoin
USDC	Base, Arbitrum, Optimism and Ethereum
USDT0	Arbitrum and Optimism
USDT	Ethereum and TRON

The gateway is free and open source (MIT). Perly Pay costs 2.5¢ a payment, never more than 0.5% of it, billed after the month. A month of up to 21 payments costs $0. Nothing is taken from the payment: see Pricing.

Test

With a sk_test_… key, pay an invoice in the client area with Perly Pay. Pay it with test coins, or from the API — the invoice id inv_… is on the checkout page:

bash

curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'

Within seconds the Blesta invoice is Paid.

How invoices follow payments

In Perly Pay	In Blesta
Paid and the sender checked (`invoice.fulfilled`)	A transaction for the amount billed, applied to the invoices it pays, and the client is emailed, as for any payment. The transaction id is the Perly Pay invoice (`inv_…`), its reference the first transfer (`pay_…`), its note the coin and network.
Part paid, expired, held for review	A line in the gateway log (Tools → Logs → Gateway). No payment.
Refund events	A line in the gateway log, from the refund as Perly Pay's API returns it.

A payment Blesta already has is never handed over again, so a replayed webhook records nothing twice and sends no second email. When the client comes back, Blesta's "payment received" page shows the payment as approved or pending; the webhook records it. Crypto cannot be pulled from a wallet, so there are no automatic recurring charges: each invoice is paid when the client pays it.

Refunds

Refund the transaction in Blesta as usual: the gateway opens a refund in Perly Pay, in the coin that was paid (the same share of it for part). Perly Pay emails the client for an address; you send from your wallet and paste the transaction id in Perly Pay. Blesta marks the transaction refunded once the refund is open. Blesta refunds a transaction once: refund the rest of the same payment from the Perly Pay dashboard.

Go live

Turn on live mode in Perly Pay and connect your wallet's public keys.
Paste a sk_live_… key. Live keys and webhooks are separate from test ones: add the callback address again as a live webhook and paste its secret.
For the overlay, add your Blesta's https address to Sites that may embed the checkout in live mode too: test and live keep separate lists.
Pay one small real invoice and refund it.