Quickstart

Send your first payment in under 10 minutes.

# Your API key looks like this
nz_live_sk_a8f3d2c1e4b5a6f7...
nz_test_sk_b9c3d4e5f6a7b8c9...  # sandbox

curl -X POST https://sandbox.stablique.xyz/v1/accounts/topup \
  -H "Authorization: Bearer nz_test_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000.00",
    "asset": "USDT",
    "chain": "tron"
  }'

curl -X POST https://sandbox.stablique.xyz/v1/payments/send \
  -H "Authorization: Bearer nz_test_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-123" \
  -d '{
    "amount": "250.00",
    "source_currency": "USDT",
    "destination_currency": "KES",
    "corridor": "DRC-KE",
    "recipient": {
      "name": "Amara Diallo",
      "phone": "+254712345678",
      "payout_method": "mpesa"
    },
    "reference": "invoice_2026_0042"
  }'

curl -X POST https://sandbox.stablique.xyz/v1/webhooks \
  -H "Authorization: Bearer nz_test_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/stablique",
    "events": ["payment.settled", "payment.failed"]
  }'

Authentication

Stablique API uses Bearer token authentication. Include your API key in the Authorization header of every request.

API key format

Authorization: Bearer nz_live_sk_<key>

Key types

Key scopes

Each API key can be scoped to specific permissions. Create scoped keys in the dashboard for least-privilege access.

Security requirements

API keys grant full access to your Stablique account. Follow these requirements:

• Never expose keys in client-side code, mobile apps, or public repositories
• Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault)
• Rotate keys immediately if you suspect compromise — use the dashboard or DELETE /v1/api-keys/{id}
• Use scoped keys for each service — one key per microservice, minimum required permissions

SDKs & libraries

Official Stablique SDKs for Node.js, Python, and PHP. All SDKs are open source and maintained by Stablique.

Node.js / TypeScript

npm install @stablique/payments

import { StabliqueClient } from '@stablique/payments';

const client = new StabliqueClient({
  apiKey: process.env.STABLIQUE_API_KEY,
  environment: 'production' // or 'sandbox'
});

// Send a payment
const payment = await client.payments.send({
  amount: '250.00',
  sourceCurrency: 'USDT',
  destinationCurrency: 'KES',
  corridor: 'DRC-KE',
  recipient: {
    name: 'Amara Diallo',
    phone: '+254712345678',
    payoutMethod: 'mpesa'
  },
  reference: 'invoice_2026_0042',
  idempotencyKey: 'inv-0042-send-1'
});

console.log(payment.id, payment.status);
// pay_01HX4K9MZTP8... pending_quote

Python

pip install stablique

from stablique import StabliqueClient

client = StabliqueClient(
    api_key=os.environ["STABLIQUE_API_KEY"],
    environment="production"
)

payment = client.payments.send(
    amount="250.00",
    source_currency="USDT",
    destination_currency="KES",
    corridor="DRC-KE",
    recipient={
        "name": "Amara Diallo",
        "phone": "+254712345678",
        "payout_method": "mpesa"
    },
    reference="invoice_2026_0042",
    idempotency_key="inv-0042-send-1"
)

PHP

composer require stablique/payments

use Stablique\Payments\StabliqueClient;

$client = new StabliqueClient([
    'api_key'    => $_ENV['STABLIQUE_API_KEY'],
    'environment' => 'production',
]);

$payment = $client->payments->send([
    'amount'               => '250.00',
    'source_currency'      => 'USDT',
    'destination_currency' => 'KES',
    'corridor'             => 'DRC-KE',
    'recipient'            => [
        'name'          => 'Amara Diallo',
        'phone'         => '+254712345678',
        'payout_method' => 'mpesa',
    ],
]);

Sandbox

The Stablique sandbox is a fully isolated test environment. No real funds move. Off-ramp partners are simulated. Use it freely in development and CI.

Base URL

https://sandbox.stablique.xyz/v1

Sandbox behaviour

Test scenarios

Use these magic values to trigger specific sandbox behaviours:

Sandbox API key

Your sandbox key is available immediately on signup — no KYB required. It has the prefix nz_test_sk_ and only works against the sandbox base URL.

Send a payment

Initiates a payment. Stablique API fetches quotes from available corridor partners, selects the best route, settles USDT on-chain, and delivers fiat to the recipient. Returns immediately with a payment object in pending_quote state.

Request headers

Request body

Recipient object

Example request

copy{
  "amount": "250.00",
  "source_currency": "USDT",
  "destination_currency": "KES",
  "corridor": "DRC-KE",
  "recipient": {
    "name": "Amara Diallo",
    "phone": "+254712345678",
    "payout_method": "mpesa"
  },
  "reference": "invoice_2026_0042",
  "metadata": {
    "customer_id": "cust_8821"
  }
}

Response

copy{
  "id": "pay_01HX4K9MZTP8VKWJ3RDF7GN2C",
  "status": "pending_quote",
  "amount": "250.00",
  "source_currency": "USDT",
  "destination_currency": "KES",
  "corridor": "DRC-KE",
  "recipient": {
    "name": "Amara Diallo",
    "phone": "+254712345678",
    "payout_method": "mpesa"
  },
  "reference": "invoice_2026_0042",
  "quote": null,
  "chain_tx": null,
  "fees": null,
  "created_at": "2026-05-28T14:32:11.000Z",
  "updated_at": "2026-05-28T14:32:11.000Z",
  "metadata": { "customer_id": "cust_8821" }
}

{
  "error": {
    "code": "validation_error",
    "message": "recipient.phone is required for payout_method mpesa",
    "field": "recipient.phone"
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "Available USDT balance (180.00) is less than requested amount (250.00)",
    "available": "180.00",
    "requested": "250.00"
  }
}

Get a payment

Retrieve a payment by its ID. Use this to poll for status updates or to retrieve full payment details including fees, chain transaction hash, and quote details once the payment has progressed.

Path parameters

Example response — settled payment

copy{
  "id": "pay_01HX4K9MZTP8VKWJ3RDF7GN2C",
  "status": "payout_settled",
  "amount": "250.00",
  "source_currency": "USDT",
  "destination_currency": "KES",
  "destination_amount": "32150.00",
  "corridor": "DRC-KE",
  "recipient": {
    "name": "Amara Diallo",
    "phone": "+254712345678",
    "payout_method": "mpesa"
  },
  "quote": {
    "partner": "kotani_pay",
    "rate": "128.60",
    "expires_at": "2026-05-28T14:32:41.000Z"
  },
  "chain_tx": {
    "chain": "tron",
    "hash": "0x4a3f8b2c1e9d7f6a...",
    "confirmed_at": "2026-05-28T14:32:18.000Z"
  },
  "fees": {
    "platform_fee": "0.875",
    "network_fee": "0.10",
    "partner_fee": "0.50",
    "total_fee": "1.475",
    "fee_currency": "USDT"
  },
  "reference": "invoice_2026_0042",
  "created_at": "2026-05-28T14:32:11.000Z",
  "settled_at": "2026-05-28T14:34:52.000Z",
  "updated_at": "2026-05-28T14:34:52.000Z"
}

List payments

Returns a paginated list of payments for your account, ordered by created_at descending.

Query parameters

Response

{
  "data": [ /* array of payment objects */ ],
  "has_more": true,
  "next_cursor": "pay_01HX4K...",
  "total": 1847
}

Get quotes

Fetch real-time quotes for a corridor and amount. Returns all available off-ramp partner quotes, ranked by best effective rate. Quotes are valid for 30 seconds.

You typically do not need to call this endpoint directly — POST /payments/send automatically selects the best quote. Use this endpoint if you want to show the user a rate before initiating payment.

Query parameters

Response

{
  "quotes": [
    {
      "id": "qt_01HX4K9MZTP8VKWJ",
      "partner": "kotani_pay",
      "rate": "128.60",
      "destination_amount": "32150.00",
      "fee": "0.50",
      "payout_method": "mpesa",
      "estimated_payout_minutes": 3,
      "expires_at": "2026-05-28T14:32:41.000Z"
    },
    {
      "id": "qt_01HX4K9MZTP8VKWK",
      "partner": "yellow_card",
      "rate": "127.80",
      "destination_amount": "31950.00",
      "fee": "0.75",
      "payout_method": "mpesa",
      "estimated_payout_minutes": 8,
      "expires_at": "2026-05-28T14:32:41.000Z"
    }
  ],
  "best_quote_id": "qt_01HX4K9MZTP8VKWJ"
}

Accept a quote

Lock a quote and initiate settlement. The quote must not be expired. This creates a payment and immediately begins USDT on-chain settlement.

Request body

Response

Returns a payment object in chain_settling state. The quote is locked and USDT settlement has begun.

List corridors

Returns all available corridors, their supported payout methods, currencies, and current availability status.

{
  "corridors": [
    {
      "code": "DRC-KE",
      "name": "DRC to Kenya",
      "source_currency": "USDT",
      "destination_currency": "KES",
      "payout_methods": ["mpesa", "bank_transfer"],
      "min_amount": "1.00",
      "max_amount": "50000.00",
      "status": "active",
      "estimated_settlement_minutes": { "min": 2, "max": 15 }
    }
  ]
}

Get account balance

Returns the current USDT balance for your Stablique account.

{
  "available": "9483.25",
  "pending": "250.00",
  "total": "9733.25",
  "currency": "USDT",
  "updated_at": "2026-05-28T14:32:11.000Z"
}

Top up account

Returns a USDT deposit address for a specific chain. Send USDT to this address to credit your Stablique account. Credits typically appear within 1–3 block confirmations.

Request body

Response

{
  "deposit_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW",
  "chain": "tron",
  "asset": "USDT",
  "expected_amount": "1000.00",
  "memo": null,
  "expires_at": null
}

Withdraw

Withdraw USDT from your Stablique account to an external wallet. Withdrawals require account:write scope and are subject to AML screening.

Request body

Webhook guide

Stablique API sends HMAC-signed webhook events to your registered endpoints whenever a payment changes state. Webhooks are the recommended way to track payment status — do not poll GET /payments/{id} in a loop.

Event types

Payload structure

{
  "event_id": "evt_01HX4K9MZTP8VKW",
  "event_type": "payment.settled",
  "created_at": "2026-05-28T14:34:52.000Z",
  "data": {
    /* full payment object */
  }
}

Verifying signatures

Every webhook request includes an X-Stablique-Signature header. Verify it before processing the payload.

// Node.js verification
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expected)
  );
}

Delivery & retries

Stablique API expects a 2xx response within 10 seconds. If your endpoint fails or times out, we retry with exponential backoff:

After 10 failed attempts the event is moved to the dead-letter queue. You can replay dead-lettered events from the dashboard.

Register a webhook

Request body

Response

{
  "id": "wh_01HX4K9MZTP8VKW",
  "url": "https://yourapp.com/webhooks/stablique",
  "events": ["payment.settled", "payment.failed"],
  "secret": "whsec_a8f3d2c1e4b5...",
  "status": "active",
  "created_at": "2026-05-28T14:32:11.000Z"
}

List webhooks

Returns all registered webhook endpoints for your account.

Delete a webhook

Permanently deletes a webhook endpoint. In-flight deliveries will still attempt to complete. Returns 204 No Content on success.

Errors

Stablique API uses standard HTTP status codes and machine-readable error codes in every error response.

Error response format

{
  "error": {
    "code": "insufficient_balance",
    "message": "Human-readable description of the error",
    "request_id": "req_01HX4K9M..."
  }
}

HTTP status codes

Error codes

Idempotency

All state-changing endpoints (POST) support idempotency keys. Always use them for payment operations.

Pass a unique string in the Idempotency-Key header. If a request fails mid-flight or you're unsure whether it was received, resubmit it with the same key — Stablique API will return the original response rather than creating a duplicate payment.

Key rules

• Keys are scoped to your API key — different API keys can use the same idempotency key safely
• Keys are valid for 24 hours after the original request
• If you submit the same key with different request parameters, you receive a 409 Conflict error
• Use UUIDs (v4) — they are collision-resistant and statistically unique

Recommended pattern

// Generate a stable key from your own reference
const { v4: uuidv4 } = require('uuid');

// Option A: random UUID per attempt (simplest)
const key = uuidv4();

// Option B: deterministic from your internal ID (allows safe replay)
const key = `payment-${your_internal_id}-${attempt_number}`;

Payment lifecycle

Every Stablique API payment moves through a defined sequence of states from creation to final settlement or failure.

Typical timing

Compliance & KYC

Stablique API performs KYT (Know Your Transaction) screening on every payment. You are responsible for KYB (Know Your Business) verification of your own customers.

What Stablique screens

• Every payment is screened against OFAC, EU, and UN sanctions lists
• On-chain transaction addresses are checked via Chainalysis for source-of-funds risk
• High-risk transaction patterns trigger automatic compliance holds

Your responsibilities

• You must complete KYB verification before accessing production
• You are responsible for KYC on your own end users — Stablique's screening is supplemental, not a substitute
• Do not initiate payments for customers you have reason to believe are sanctioned or using proceeds of crime
• Respond to compliance hold notifications within 48 hours with any requested information

Changelog

API version history and breaking changes.

v1.0.0 — May 2026

Initial release.

• POST /payments/send — send stablecoin-settled payments
• GET /payments/{id} and GET /payments — payment retrieval and listing
• GET /quotes and POST /quotes/{id}/accept — quote management
• GET /corridors — corridor availability
• GET|POST /accounts/balance|topup|withdraw — account management
• POST|GET|DELETE /webhooks — webhook management
• Live corridors: DRC-KE, DRC-DRC, KE-KE, NG-KE, IN-KE
• Off-ramp partners: Yellow Card, Kotani Pay, Ovex, TransFi, Mudrex