# FOSSBilling > Accept cryptocurrency payments in FOSSBilling through Cryptonly hosted checkout. **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](https://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 1. Sign up at [cryptonly.net](https://cryptonly.net) (or [sandbox-merchant.cryptonly.net](https://sandbox-merchant.cryptonly.net) for testing). 2. Open **Accounts**, select the account, then **Settings → Security**. Create an **API key**. The key selects that account. 3. 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 1. Download the Cryptonly adapter from the [FOSSBilling extension directory](https://extensions.fossbilling.org/extension/cryptonly-crypto-payment-gateway). 2. 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: ```text library/Payment/Adapter/Cryptonly/Cryptonly.php ``` 3. 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](https://docs.cryptonly.net/integration/plugins/fossbilling.md#api-key-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: ```text {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`) | :::caution **Webhook Signing Key is mandatory.** Saving an API key without a signing key is blocked. Test mode must match your API key environment (sandbox vs production). ::: Saving the gateway validates the API key with Cryptonly `GET /currencies`. *** ## Test in sandbox 1. Enable **Test mode** and enter credentials from [sandbox-merchant.cryptonly.net](https://sandbox-merchant.cryptonly.net). 2. Confirm the FOSSBilling URL Cryptonly will call is public HTTPS. 3. Open a test invoice and choose **Pay with Cryptonly**. 4. 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](https://docs.cryptonly.net/guides/testing-your-integration.md). 5. Confirm the invoice is paid, or that a partial payment appears as account credit. :::caution Sandbox uses testnets only. Do not send mainnet funds to sandbox payment addresses. ::: *** ## 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 *** ## Related documentation - [Webhooks](https://docs.cryptonly.net/api-reference/webhooks.md): Verification and payload details - [Invoices](https://docs.cryptonly.net/guides/invoices.md): How checkout payments work - [Testing your integration](https://docs.cryptonly.net/guides/testing-your-integration.md): History and test webhooks *** ## Support For help with your Cryptonly merchant account, credentials, or payment questions, visit [Cryptonly](https://cryptonly.net) or write to support@cryptonly.net.