Appearance
Merchant payments
The merchant module turns your exchange into a crypto payment provider. A business opens a merchant account, creates invoices (by hand or through the API), and its customers pay on a hosted checkout page. Paid amounts are added to the merchant's balance, which they pay out to their own wallet.
Turning the module on
Set MERCHANT_ACQUIRING_ENABLED=true in .env and run php artisan config:clear. Then Merchant appears in signed-in users' account menu, and the Merchant section in the admin panel (Admin → Merchant). Coins merchants can be paid in are chosen in Currencies → Merchant payments.
Becoming a merchant
Page: /merchant/apply. The user enters the business name, business email, optionally the website, a description and country, and accepts the terms.
The account starts as pending until your team approves it in Admin → Merchant → Merchants. Merchants can be active, suspended or terminated. A rejected applicant can apply again.
The merchant dashboard
| Page | Address | For |
|---|---|---|
| Dashboard | /merchant/dashboard | Volume, recent invoices, balance |
| Invoices | /merchant/invoices, /merchant/invoices/create | Creating and following invoices |
| Earnings | /merchant/earnings | Balance per coin and fees paid |
| Deposits | /merchant/deposits | Each payment received |
| Payouts | /merchant/payouts | Withdrawing the balance |
| Webhooks | /merchant/webhooks | Notifications sent to the merchant's server |
| Settings · API keys | /merchant/settings, /merchant/settings/api-keys | Webhook address and secret, payout address, API keys |
| Developer docs | /merchant/docs | The integration guide |
Invoices and the hosted checkout
An invoice is a payment request for an amount (in a fiat currency or a coin). Each invoice has a checkout page at:
txt
https://yourdomain.com/pay/i/<invoice-id>The merchant sends the customer there (a link, a button on their shop, or a redirect). On the checkout:
- The customer chooses a coin and network among those the merchant accepts. They have 60 minutes to choose.
- The page shows an amount, a one-time deposit address and a QR code. The exchange rate is locked for 15 minutes (it can be extended twice by 5 minutes).
- The customer pays within 30 minutes.
The scheduler watches invoice addresses every minute on Ethereum, Tron, BNB Smart Chain, Polygon, Solana and Bitcoin (merchant:monitor-deposits, merchant:monitor-btc-deposits), with the same scanners as user deposits. TON and XRP invoices share your hot wallet address and are told apart by their memo; the TON / XRP deposit monitors pick them up. Paid funds move to your wallets every 5 minutes (merchant:collect-funds).
Invoice statuses
| Status | Meaning |
|---|---|
| Awaiting selection | Waiting for the customer to choose a coin |
| Awaiting payment | Address shown, nothing received yet |
| Detecting / Confirming | Payment seen, waiting for confirmations |
| Paid | Paid in full |
| Overpaid / Underpaid | More or less than the amount arrived |
| Settled | Credited to the merchant's balance |
| Expired | Not paid in time |
| Cancelled | Cancelled by the merchant |
| Failed | Couldn't be processed |
| Refunding / Refunded | A refund is being sent / was sent |
A payment that matches no invoice (wrong amount, or after expiry) appears under Unmatched payments in the admin panel.
Fees
Each coin has a processing fee for merchant payments, set on the currency (Currencies). It's deducted from what the merchant receives. Your earnings are listed in Admin → Merchant → Earnings.
Webhooks
When something happens to an invoice (paid, expired, refunded…), the platform sends a POST to the merchant's webhook URL with a JSON body and these headers:
| Header | Content |
|---|---|
X-Webhook-Id | Unique ID of this notification |
X-Event-Type | The event, for example an invoice being paid |
X-Webhook-Timestamp | Unix time it was signed |
X-Webhook-Signature | v1= + HMAC-SHA256 of <timestamp>.<body> with the merchant's webhook secret |
X-Idempotency-Key | Lets the merchant ignore duplicates |
The merchant's server must check the signature and answer with a 2xx status. Failed deliveries are retried 5 times: after 30 seconds, 2 minutes, 10 minutes, 1 hour and 4 hours. After that the notification moves to Failed (dead letters), and can be retried from the admin panel or with php artisan merchant:retry-dead-letters. Merchants can send a test webhook and rotate their secret from their settings.
Payouts
Merchants withdraw their balance from Payouts: they set a payout address per coin in their settings, then request a payout. Requests start as pending and must be approved in the admin panel. Approved payouts are sent from your hot wallets and end as completed (or rejected / failed, when the amount goes back to the balance). A pending request can be cancelled by the merchant.
Refunds
A merchant can refund a paid invoice (through the API: POST /api/v1/merchant/invoices/<id>/refund). The refund goes through pending → processing → sending → completed (or failed / cancelled), and is sent by merchant:process-refunds. Refunding a settled invoice needs enough available balance.
Sending approved payouts and refunds
Approved payouts and approved refunds are sent automatically every 2 minutes (merchant:process-payouts and merchant:process-refunds, scheduled by the merchant module itself). In the admin panel an admin can also send one at once. See Admin → Merchant → Reviewing payouts and Refunds.
The merchant API
Developers integrate with the REST API at https://yourdomain.com/api/v1/merchant/…:
| Endpoint | Does |
|---|---|
POST /invoices, GET /invoices, GET /invoices/{id}, GET /invoices/{id}/status | Create, list and check invoices |
POST /invoices/{id}/cancel, POST /invoices/{id}/refund | Cancel or refund |
GET /balance, GET /payments, GET /account | Balance, payments, account |
GET /currencies, GET /currencies/{code}/rate | Accepted coins and live rates |
GET /webhooks, POST /webhooks/test, POST /webhook-secret/rotate | Webhook tools |
Every request is signed with the merchant's API key pair:
| Header | Content |
|---|---|
X-API-Key | The public API key |
X-Timestamp | Current Unix time. Requests more than 30 seconds old are refused. |
X-Signature | HMAC-SHA256 of <timestamp>.<METHOD>.<path>.<body> with the API secret |
Merchants create and revoke API keys under Settings → API keys. The complete guide, with examples, is on /merchant/docs in their dashboard.
Settings for the platform owner
.env | Default | Meaning |
|---|---|---|
MERCHANT_ACQUIRING_ENV | live | live or sandbox |
INVOICE_SELECTION_EXPIRY | 3600 | Seconds to choose a coin |
INVOICE_PAYMENT_EXPIRY | 1800 | Seconds to pay |
INVOICE_RATE_VALIDITY | 900 | Seconds the rate is locked |
RATE_SOURCE | binance | Where invoice rates come from: binance, coingecko, internal or fixed |
