Skip to content

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.

10 minutesUser featureSite owner, merchantsVerified against the platform code

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 ​

PageAddressFor
Dashboard/merchant/dashboardVolume, recent invoices, balance
Invoices/merchant/invoices, /merchant/invoices/createCreating and following invoices
Earnings/merchant/earningsBalance per coin and fees paid
Deposits/merchant/depositsEach payment received
Payouts/merchant/payoutsWithdrawing the balance
Webhooks/merchant/webhooksNotifications sent to the merchant's server
Settings · API keys/merchant/settings, /merchant/settings/api-keysWebhook address and secret, payout address, API keys
Developer docs/merchant/docsThe 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:

  1. The customer chooses a coin and network among those the merchant accepts. They have 60 minutes to choose.
  2. 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).
  3. 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 ​

StatusMeaning
Awaiting selectionWaiting for the customer to choose a coin
Awaiting paymentAddress shown, nothing received yet
Detecting / ConfirmingPayment seen, waiting for confirmations
PaidPaid in full
Overpaid / UnderpaidMore or less than the amount arrived
SettledCredited to the merchant's balance
ExpiredNot paid in time
CancelledCancelled by the merchant
FailedCouldn't be processed
Refunding / RefundedA 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:

HeaderContent
X-Webhook-IdUnique ID of this notification
X-Event-TypeThe event, for example an invoice being paid
X-Webhook-TimestampUnix time it was signed
X-Webhook-Signaturev1= + HMAC-SHA256 of <timestamp>.<body> with the merchant's webhook secret
X-Idempotency-KeyLets 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/…:

EndpointDoes
POST /invoices, GET /invoices, GET /invoices/{id}, GET /invoices/{id}/statusCreate, list and check invoices
POST /invoices/{id}/cancel, POST /invoices/{id}/refundCancel or refund
GET /balance, GET /payments, GET /accountBalance, payments, account
GET /currencies, GET /currencies/{code}/rateAccepted coins and live rates
GET /webhooks, POST /webhooks/test, POST /webhook-secret/rotateWebhook tools

Every request is signed with the merchant's API key pair:

HeaderContent
X-API-KeyThe public API key
X-TimestampCurrent Unix time. Requests more than 30 seconds old are refused.
X-SignatureHMAC-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 ​

.envDefaultMeaning
MERCHANT_ACQUIRING_ENVlivelive or sandbox
INVOICE_SELECTION_EXPIRY3600Seconds to choose a coin
INVOICE_PAYMENT_EXPIRY1800Seconds to pay
INVOICE_RATE_VALIDITY900Seconds the rate is locked
RATE_SOURCEbinanceWhere invoice rates come from: binance, coingecko, internal or fixed

Owner documentation for the CryptoTech exchange platform.