FOSSBilling

Cryptonly lets your FOSSBilling site accept Bitcoin, stablecoins, and other cryptocurrencies through Cryptonly’s hosted checkout. Customers pay on the Cryptonly payment page. FOSSBilling records the money only after a signed webhook.

A payment smaller than the invoice total is added as account credit. FOSSBilling marks the invoice paid when that credit covers the invoice total. An overpay is capped at the amount still due and is not stored as extra credit.

Requirements

Requirement	Details
FOSSBilling	0.7 or newer
PHP	8.2 or newer
Cryptonly account	cryptonly.net merchant account
Credentials	API key and webhook signing key from the account’s Accounts → Settings → Security page
Public HTTPS URL	Required so Cryptonly can deliver webhooks. Cryptonly does not follow redirects

Before you install — Cryptonly account

Sign up at cryptonly.net (or sandbox-merchant.cryptonly.net for testing).
Open Accounts, select the account, then Settings → Security. Create an API key. The key selects that account.
On the same page, under Webhook signing key, click Rotate key and copy the secret when it is shown. It appears only once, and the previous key stops working immediately.

Install the adapter

Download the Cryptonly adapter from the FOSSBilling extension directory.
Extract the archive in your FOSSBilling root (FTP, SFTP, or your hosting file manager). The zip already contains the library/ folder, so it merges with the existing one.

After extraction, this file should exist:
```
library/Payment/Adapter/Cryptonly/Cryptonly.php
```
Open System → Payment gateways → New payment gateway and install Cryptonly.

Configure the gateway

Fill in the fields on the Cryptonly gateway form:

FOSSBilling field	What to enter
API Key	Cryptonly API key. The key selects the account. See required scopes
Webhook Signing Key	Required. Payments are confirmed only via webhooks
Order ID Prefix	Optional. Default `FOSS` produces `FOSS-12`, then `FOSS-12-2` on a later attempt
Test mode	Enable to use the Cryptonly sandbox API for testing

The adapter sends the webhook URL with each invoice, so you do not paste it into the Cryptonly dashboard. FOSSBilling calls:

{siteurl}ipn.php?gateway_id={gateway_id}&invoice_id={invoice_id}

Leave the API key or signing key blank on a later save to keep the stored value.

API key scopes

Create the key on the account’s Accounts → Settings → Security page and enable only these scopes:

Scope	Used for
`currencies.list`	Confirm the API key when saving the gateway (`GET /currencies`)
`invoices.list`	Reuse a payable invoice or choose the next `orderId`, and load the invoice when create returns a duplicate (`GET /invoice`)
`invoices.create`	Create the invoice at checkout (`POST /invoice`)

Saving the gateway validates the API key with Cryptonly GET /currencies.

Test in sandbox

Enable Test mode and enter credentials from sandbox-merchant.cryptonly.net.
Confirm the FOSSBilling URL Cryptonly will call is public HTTPS.
Open a test invoice and choose Pay with Cryptonly.
Complete payment on the Cryptonly hosted page (testnet only in sandbox), or use Simulate payment on the invoice in Cryptonly Accounts → History to settle it without sending testnet funds. See Testing your integration.
Confirm the invoice is paid, or that a partial payment appears as account credit.

How FOSSBilling invoices are updated

The adapter listens for invoice.statusChanged webhooks. Returning from the hosted page does not mark the invoice paid.

Cryptonly invoice status	FOSSBilling behavior
`created`, `processing`	No credit recorded
`suspended`	No credit recorded
`paid`, `overpaid`	The amount still due is added as account credit, then the invoice is paid from that credit. An overpay is not stored
`partially_paid`	`settlement.amountPaid` is added as account credit. The invoice stays unpaid
`expired`, `failed`, `cancelled`	No credit recorded. A later `paid` can still be applied

The next checkout after a partial charges what is still due. The order id is FOSS-12, then FOSS-12-2 on a later attempt.

Cryptonly invoice expiry follows the FOSSBilling due date, from 15 minutes up to 30 days. An invoice past its due date cannot start a new checkout.

Subscriptions are off. A renewal invoice is paid with a new checkout.

Go live checklist

Before accepting real payments:

Turn off Test mode
Enter production API Key and Webhook Signing Key
Confirm the site URL is public HTTPS
Place a small real test payment and confirm the invoice is paid

FOSSBilling extension listing

WebhooksVerification and payload details

InvoicesHow checkout payments work

Testing your integrationHistory and test webhooks

Support

For help with your Cryptonly merchant account, credentials, or payment questions, visit Cryptonly or write to [email protected].