Hbridge Docs
API reference

Payment requests

The core of the dynamic-wallet flow: create a one-time address and amount for a payment, then track it until it's paid. All endpoints authenticate with the x-api-key header.

List assets#

GET/v1/crypto

List the assets you can currently collect. Use the name field as the :currency path segment when creating a payment request.

Request
GET https://api.hbridge.cc/v1/crypto
x-api-key: sk_live_...
200 Response
{
  "code": 200,
  "data": [
    { "name": "BTC", "display_name": "Bitcoin" },
    { "name": "ETH", "display_name": "Ethereum" },
    { "name": "USDT", "display_name": "Tether" }
  ]
}

Create payment request#

Creates a one-time deposit address for a single payment. The response data carries the address the customer must pay into and the exact amount to collect. Show these on your checkout, along with a QR code.

POST/v1/:currency/payment-request

Create a payment request for :currency (an asset name from /v1/crypto, e.g. BTC).

Path
FieldTypeRequiredDescription
currencystringyesAsset code, e.g. BTC, ETH, USDT.
Body
FieldTypeRequiredDescription
external_idstringyesYour unique reference for this payment. Must be prefixed with your account prefix (see External IDs). Reusing an external_id is rejected.
amountstringyesThe amount to collect, in the asset's units.
Request
POST https://api.hbridge.cc/v1/BTC/payment-request
x-api-key: sk_live_...
Content-Type: application/json

{
  "external_id": "1042-order-9f3c",
  "amount": "0.0025"
}
200 Response
{
  "code": 200,
  "message": "Payment Request Received",
  "data": {
    "external_id": "1042-order-9f3c",
    "currency": "BTC",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "amount": "0.0025"
  }
}

The data object mirrors the payment gateway response; always render the returned address and amount rather than assuming them.

400: External Id already present. Each external_id can back exactly one payment request; generate a fresh one per checkout attempt.

External IDs#

The external_id ties a payment to your system and must start with your account prefix followed by -. Requests whose prefix doesn't match your account are rejected with 400 Bad Request.

Format
<prefix>-<your-reference>

# e.g. account prefix 1042:
1042-order-9f3c
1042-invoice-2026-0007

Keep the reference unique and collision-free on your side (an order id plus a random suffix works well), since it's also the key you'll track the payment by.

Track payments#

Poll your payments to learn when a request has been paid. Match on the external_idyou created and check its status; a payment appears here once it's been detected and settled.

GET/payments

List payments for your account, so you can reconcile a payment request by its external_id.

Request
GET https://api.hbridge.cc/payments
x-api-key: sk_live_...
200 Response
{
  "code": 200,
  "data": [
    {
      "external_id": "1042-order-9f3c",
      "currency": "BTC",
      "amount": "0.0025",
      "status": "paid",
      "txid": "9f2a...c81",
      "paid_at": "2026-07-22T10:31:00.000Z"
    }
  ]
}

In the current dynamic-wallet system, clients confirm payments by polling this endpoint rather than receiving a webhook; the checkout callback is handled inside the platform.

PreviousOverviewNextIntegration walkthrough