> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billions.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Unified Merchant API

> Connect existing merchant-style SDKs and payment modules to Billions.

The Unified Merchant API lets an existing payment integration create Billions
invoices with limited changes to its configuration. Use this path if your
application or store already has a compatible SDK or module. For a new
integration, use the [Billions Public API](/api/overview) or an
[official Billions SDK](/sdks/overview).

## Connect an existing integration

<Steps>
  <Step title="Create a Billions API key">
    In your Billions account settings, create an API key and save both values
    returned when it is issued: `apiKey` and `secretKey`. The secret is shown
    only once. Keep it on your server.
  </Step>

  <Step title="Change the API base URL">
    Replace the existing API base URL inside the SDK or module with
    `https://compatibility-cm.billions.works`. Keep the module's `/v1/...`
    endpoint paths. If its configuration contains a full URL ending in `/v1`,
    use `https://compatibility-cm.billions.works/v1` instead.
  </Step>

  <Step title="Enter the matching credentials">
    Set the module's Merchant UUID and payment secret to the values from the
    **same** Billions API key, following the mapping below.
  </Step>

  <Step title="Run a test payment">
    Create an invoice, open its returned payment URL, and confirm that the
    module receives a status update. Check the module's behavior for the
    operations it uses before enabling live checkout.
  </Step>
</Steps>

| Existing integration field | Billions value |
| - | - |
| Merchant UUID | `apiKey` — the API key UUID, not the Billions merchant's internal ID |
| Payment API Key / Secret | `secretKey` issued together with that `apiKey` |

The payment secret is used to sign requests and callbacks. Older Billions API
keys without a signing secret must be reissued. Keep the secret out of browser
code, URLs, and logs.

<Note>
  Change the URL used for **API requests**. Keep the checkout URL returned in
  the invoice response and your own callback URL as they are; the module should
  use the returned checkout URL without rewriting its host.
</Note>

## SDKs and modules

Compatible PHP SDKs can use this API for supported payment methods when their
API base URL is configurable. Some community TypeScript clients require
overriding the payment client's `baseUrl` instead; check whether that override
still works when updating the package.

Payment modules for the following platforms can be considered for this path
when their API URL can be changed and their checkout uses the supported
payment methods:

* **Stores:** WooCommerce, PrestaShop, OpenCart, Magento, BigCommerce, CS-Cart,
  PHPShop, Easy Digital Downloads, Webasyst, VirtueMart.
* **Billing and hosting:** WHMCS, BillManager, RootPanel, Clientexec, HostBill,
  Blesta, WISECP, Amember.
* **Other platforms:** XenForo, Tilda, Azuriom, Invision Community, Watbot.

Module versions and the methods they call vary. This list identifies the
available modules, **not** a guarantee that every module and feature works
unchanged. In particular, modules that require static wallets, refunds,
mark-as-paid, or webhook resend need additional support beyond the current
compatibility API. For WooCommerce, you can alternatively use the
[official Billions plugin](/store-integrations/woocommerce). For BILLmanager 6,
see the [official Billions module](/store-integrations/billmanager). For Tilda,
see the [Billions Custom Payment Gateway setup](/store-integrations/tilda). For
WHMCS, use the [official Billions gateway](/store-integrations/whmcs).

## Supported payment operations

| Method | Path | Use |
| - | - | - |
| `POST` | `/v1/payment` | Create an invoice |
| `POST` | `/v1/payment/info` | Retrieve an invoice by `uuid` or `order_id` |
| `POST` | `/v1/payment/list` | List compatible invoices |
| `POST` | `/v1/payment/services` | List available payment currencies and networks |
| `POST` | `/v1/payment/qr` | Get a QR image for an invoice with a payment address |

These endpoints use `merchant` and `sign` headers. The `sign` value is the
lowercase MD5 hex digest of the Base64-encoded **exact JSON body
bytes** followed by `secretKey`. It differs from the RFC 8785/HMAC signature
used by [Billions signed money operations](/api/request-signing). Compatible
SDKs and modules usually calculate this signature themselves.

Invoices created here send compatible callbacks to `url_callback` when
provided. Their `sign` is in the JSON body, and their format differs from
[Billions-native webhooks](/integration/callbacks-and-security). Verify and
process them according to the module's callback flow.

This is a partial payment API compatibility layer. Refunds, static wallets,
mark-as-paid, webhook resend, and payout methods are not implemented in this
API. Unsupported request options are rejected explicitly.

*Commonly used by several merchants like Cryptomus, Helekat, and NearPayments.*

*Every merchant must complete document verification and all applicable
compliance checks before processing payments. API compatibility does not waive
these requirements and is intended solely for lawful businesses and payments.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.