Merchant API

Crypto checkout API

Accept USDT and BTC directly to wallets you control. Create payment requests from your backend, receive webhook confirmations, and automate settlement — similar to Stripe Payment Intents, for stablecoins.

Single API key Prefix sc_live_ HMAC webhooks

Merchant portal Contact sales

Introduction

The Merchant API is scoped to your merchant account. Each request is authenticated with a live API key created in the merchant portal. Keys can be rotated with a grace period so you can deploy new credentials without downtime.

Keys are created under Merchant portal → Settings → API keys. The full key is shown once at creation — store it in a secrets manager.

Supported networks

tron — USDT TRC20 (recommended)
bnb — USDT BEP20
bitcoin — BTC native

Authentication

Send your secret API key on every request. Do not expose it in browsers or mobile apps.

Headers

X-Api-Key: sc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

You may also pass the key as Authorization: Bearer sc_live_….

User API vs Merchant API
User API	Key + secret (`sc_user_` / `sc_ussec_`)
Merchant API	Single key only (`sc_live_`) — standard for server-side checkout

Quickstart

cURL — create payment

curl -X POST "https://bylipa.com/api/v1/merchant/payments" \
  -H "X-Api-Key: sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usdt": 25.5,
    "external_reference": "invoice-1001",
    "network": "tron",
    "callback_url": "https://yourstore.com/webhooks/bylipa"
  }'

Response 201

{
  "payment": {
    "reference": "PAY-20260610-XYZ",
    "external_reference": "invoice-1001",
    "status": "pending",
    "amount_usdt": "25.500000",
    "settlement_address": "TMerchantWallet...",
    "expires_at": "2026-06-10T13:00:00+00:00"
  }
}

Show settlement_address and exact amount to your customer. Confirmation typically arrives within ~1 minute on-chain.

Payments

POST /v1/merchant/payments

Create payment

Field	Type	Required	Description
`external_reference`	string	Yes	Your order ID — unique per merchant
`amount_usdt`	number	*	USDT amount (TRON/BNB)
`amount_btc`	number	*	BTC amount (bitcoin network)
`amount`	number	*	Alias for asset amount
`network`	string	No	`tron` (default), `bnb`, `bitcoin`
`asset`	string	No	`USDT` or `BTC`
`callback_url`	url	No	Webhook override for this payment
`expires_in_minutes`	integer	No	5–1440, default ~60
`metadata`	object	No	Opaque JSON stored on payment

* One of amount_usdt, amount_btc, or amount is required.

GET /v1/merchant/payments/{reference}

Retrieve payment

Response

{
  "payment": {
    "reference": "PAY-20260610-XYZ",
    "status": "confirmed",
    "amount_usdt": "25.500000",
    "chain_tx_hash": "abc123...",
    "confirmed_at": "2026-06-10T12:05:00+00:00"
  }
}

GET /v1/merchant/payments

List payments

Query: status (pending, confirmed, expired), limit (default 50).

Treasury

GET /v1/merchant/balance

Get balance

Available USDT, estimated TZS cash-out, pending mobile money collections, auto-settlement status.

Response

{
  "balance": {
    "available_usdt": 1250.5,
    "estimated_tzs": 3313825,
    "sell_rate_tzs_per_usdt": 2650,
    "pending_collection_tzs": 500000
  },
  "settlement": { }
}

GET /v1/merchant/settlements

List settlements

Withdrawals, mobile money cash-outs, and auto-settlement history.

Query: limit (max 200, default 50).

POST /v1/merchant/withdraw/mpesa

Withdraw to mobile money

Field	Type	Required	Description
`amount_usdt`	number	Yes	USDT to convert and disburse
`phone`	string	No	Defaults to merchant payout phone
`mobile_operator`	string	No	`mpesa`, `tigo`, `airtel`

POST /v1/merchant/withdraw/usdt

Withdraw USDT on-chain

Request

{
  "amount_usdt": 100.0,
  "chain": "tron",
  "to_address": "TYourColdWallet..."
}

Omit to_address to use your configured settlement wallet for that chain.

POST /v1/merchant/convert

Convert TZS collections to USDT

Moves pending PayIn TZS balance into your merchant USDT wallet at the live sell rate.

Webhooks

Configure a default webhook URL in the merchant portal, or pass callback_url per payment. Events are delivered as signed POST requests.

Event	When
`payment.created`	Payment request created
`payment.confirmed`	On-chain funds received
`payment.expired`	Customer did not pay in time

Verify signatures

Headers:

X-Stablecoin-Event — event name
X-Stablecoin-Timestamp — Unix timestamp
X-Stablecoin-Signature — HMAC-SHA256 of {timestamp}.{raw_body} using your webhook secret

PHP verification example

$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_STABLECOIN_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_STABLECOIN_SIGNATURE'];
$expected = hash_hmac('sha256', $timestamp.'.'.$payload, $webhookSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Webhook payload

{
  "event": "payment.confirmed",
  "payment": {
    "reference": "PAY-20260610-XYZ",
    "external_reference": "invoice-1001",
    "status": "confirmed",
    "amount_usdt": "25.500000",
    "chain_tx_hash": "abc123..."
  }
}

Respond with HTTP 2xx within 20 seconds. Failed deliveries are logged; implement idempotent handlers keyed on reference.

Errors

See the overview error table. Common merchant errors:

401 — invalid or revoked API key
422 — duplicate external_reference or missing settlement wallet
404 — payment reference not found for your merchant