Payment API v2

Quick start

1. Create an API key for your gateway in the dashboard under Developers. 2. Create a payment with the order amount. 3. Redirect the customer to the returned checkout_url. 4. When the webhook arrives (or the customer comes back), read the payment again and ship once its status is "paid".

 curl https://coino.live/api/v2/payments \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "currency": "EUR", "order_id": "1001",
       "success_url": "https://shop.example/thanks",
       "notify_url": "https://shop.example/coino-webhook"}' 

Authentication

Send your secret key in the Authorization header of every request. Keys belong to one gateway and only see that gateway's payments. Keep them on your server: never put a key in a browser, an app or a public repository. If a key leaks, revoke it in the dashboard and create a new one.

Authorization: Bearer ck_live_...
Base URL: https://coino.live/api/v2

All amounts are decimal strings (never numbers), all times are ISO 8601 in UTC, and every answer is JSON with the result under "data".

Create a payment

Prices can be in USD or in any currency listed by GET /currencies; other currencies are converted to USD at the current rate when the payment is created. The customer chooses the coin and network on the payment page.

The answer (201 when created, 200 for a repeated key) is the payment object below.

The payment object

{
  "data": {
    "id": "01m62ewd502p9774d6trd7rhr7",
    "status": "paid",
    "amount": "22.32",
    "currency": "USD",
    "requested_amount": "20.00",
    "requested_currency": "EUR",
    "exchange_rate_usd": "1.115926958947",
    "received_usd": "22.32",
    "remaining_usd": "0.00",
    "order_id": "943",
    "description": "Order #943",
    "customer_email": "[email protected]",
    "metadata": {"cart": "abc"},
    "checkout_url": "https://coino.live/pay/01m62ewd502p9774d6trd7rhr7",
    "success_url": "https://shop.example/thanks",
    "cancel_url": "https://shop.example/cart",
    "asset": null,
    "quote": {
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "address": "0x8e2e…61bc", "amount": "22.330545",
      "network_fee": "0.000001", "rate_usd": "0.9995", "expires_at": "…"
    },
    "deposits": [{
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "tx_hash": "0xf13d…1439", "explorer_url": "https://etherscan.io/tx/0xf13d…1439",
      "amount": "22.330545", "network_fee": "0.000001",
      "platform_fee": "0.223305", "net": "22.107239",
      "usd_value": "22.32", "credited_at": "…"
    }],
    "expires_at": "…", "paid_at": "…", "created_at": "…"
  }
}

amount and currency are what the customer pays in USD; requested_amount and requested_currency are what you asked for. quote is the coin, address and amount currently shown to the customer; deposits lists every transaction received, with the fee taken and what was added to your balance (net).

A payment within a small tolerance of the amount counts as paid, so rounding by wallets does not leave orders open.

Read and cancel payments

Read a payment again whenever you need its current state: after a webhook, when the customer returns, or from a scheduled job. Unknown IDs and other gateways' payments answer 404.

Lists your payments, newest first, 50 per page. Both filters are optional. meta.next_cursor and meta.prev_cursor page through the results.

Cancels an open payment that has received nothing, for example when the customer empties the cart. Payments with a deposit cannot be cancelled (422).

Webhooks

Coino Live sends a POST to notify_url (or the gateway webhook URL) whenever a payment changes status. Webhooks are only sent when your gateway has a signing secret: create it in the gateway settings.

 POST /coino-webhook
X-Coino-Event: payment.paid
X-Coino-Delivery: 01m62f23xhkz39ahqv4h64ttfk
X-Coino-Signature: t=1761696953,v1=5f2c…

{"id": "01m62f23xhkz39ahqv4h64ttfk", "event": "payment.paid",
 "created_at": "…", "data": { …the payment object… }} 

Check the signature: compute HMAC-SHA256 of "<t>.<raw body>" with your signing secret, compare it with v1 in constant time, and refuse timestamps older than five minutes.

// PHP
$header = $_SERVER['HTTP_X_COINO_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $sig);
$ok = isset($sig['t'], $sig['v1'])
    && abs(time() - (int) $sig['t']) <= 300
    && hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = Math.abs(Date.now() / 1000 - t) <= 300
  && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

# Python
t, v1 = (p.split('=', 1)[1] for p in header.split(','))
expected = hmac.new(secret.encode(), f'{t}.{raw_body}'.encode(), 'sha256').hexdigest()
ok = abs(time.time() - int(t)) <= 300 and hmac.compare_digest(expected, v1)

Currencies, coins and balances

Currencies a payment can be priced in, each with its USD value: {"code": "EUR", "usd_per_unit": "1.09"}. Hide crypto payment when your shop currency is not listed.

Coins customers can pay with right now: code (for example "usdt-tron"), symbol, name, network, decimals and price_usd.

Your account balance per coin, after fees: asset, symbol, network, balance and usd_value (null while no price is available).

Custody accounts

For apps with user accounts: each user gets lifetime deposit addresses, and deposits are credited to that user's balance in your gateway.

Withdrawals

Pay out from your balance to an address: asset, amount and address are required; custody_user charges a custody user's balance; reference (unique per gateway) makes the request safe to repeat. Off by default: turn on API withdrawals in the gateway settings, where you also set a daily USD limit and the server IP addresses allowed to call it (both endpoints answer only those IPs). A reference reused for a different withdrawal is refused with 409. Large withdrawals may wait for review.

Status: pending_review, approved, processing, broadcast, completed, rejected (see error), cancelled or failed. tx_hash is set once it is sent.

Errors and limits

{"message": "The minimum payment is 1.00 USD."}

{"message": "amount must be a decimal string with at most 2 decimals, e.g. \"25.00\".",
 "errors": {"amount": ["amount must be a decimal string with at most 2 decimals, e.g. \"25.00\"."]}}

Code libraries

Official libraries for this API, with no dependencies. They verify webhook signatures, raise a clear error for every refusal, and retry network errors only when repeating the request is safe.

// PHP
$coino = new \CoinoLive\Client('ck_live_...');
$payment = $coino->payments->create(['amount' => '25.00', 'currency' => 'EUR', 'order_id' => '1001']);

// Node.js
const coino = new CoinoLive('ck_live_...');
const payment = await coino.payments.create({ amount: '25.00', currency: 'EUR', order_id: '1001' });

# Python
coino = coinolive.Client("ck_live_...")
payment = coino.payments.create(amount="25.00", currency="EUR", order_id="1001") 

Each download includes a README with every call, webhook handling and the error classes.

Platform integrations

Ready-made plugins built on this API. Install one, paste an API key and enable it: orders update automatically, and each plugin shows your balance and payments inside its admin.

Other platforms: use the API directly as described above.