Settlra
v1 API · Stable

APIs Built for
Speed and Scale

Simple REST API. Comprehensive webhooks. SDKs in Node.js and Python. Go from zero to your first payout in under 10 minutes.

Get your API keyFull documentation

Quick start

From zero to a live payout in under 5 minutes using cURL or our Node.js SDK.

cURL

Quick Start — cURL
bash
# 1. Get a quote
curl -X POST https://api.settlra.io/v1/quotes \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_usdc": "25.50", "network": "mtn_uganda"}'

# 2. Execute the payout
curl -X POST https://api.settlra.io/v1/payouts \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qt_01HXYZ9ABCDEF",
    "recipient": {
      "phone": "+256700123456",
      "network": "mtn_uganda",
      "name": "Grace Nakamura"
    },
    "idempotency_key": "order_8821"
  }'

Node.js SDK

Quick Start — Node.js
typescript
import Settlra from '@settlra/node';

const client = new Settlra({ apiKey: process.env.SETTLRA_API_KEY });

// Get a quote
const quote = await client.quotes.create({
  amount_usdc: '25.50',
  network: 'mtn_uganda',
});

// Execute the payout
const payout = await client.payouts.create({
  quote_id: quote.id,
  recipient: {
    phone: '+256700123456',
    network: 'mtn_uganda',
    name: 'Grace Nakamura',
  },
  idempotency_key: 'order_8821',
});

console.log(payout.status); // 'processing'

Everything you need

REST API

Clean, predictable REST endpoints. JSON request/response with consistent error codes and detailed messages.

Webhooks

Real-time event notifications for every payout state change. Signed payloads with HMAC-SHA256 verification.

Node.js & Python SDKs

Official SDKs with full TypeScript types. Auto-retry on transient errors, built-in idempotency support.

Sandbox Environment

Full test environment at api-sandbox.settlra.io. Simulate success, failure, and delay scenarios.

Idempotency

Safe retries with idempotency keys. Duplicate requests return the original response — no double payouts.

Status Page

Real-time operational status for all networks. Subscribe to incident notifications via email or webhook.

API endpoints

Base URL: https://api.settlra.io

Method
Endpoint
Description
Auth
POST
/v1/quotes
Create a conversion quote (valid for 60 seconds)
🔑
POST
/v1/payouts
Execute a payout using a valid quote ID
🔑
GET
/v1/payouts/:id
Retrieve the status of a payout
🔑
GET
/v1/payouts
List payouts with pagination and filtering
🔑
POST
/v1/webhooks
Register a webhook endpoint
🔑
GET
/v1/networks
List supported networks and their current status
—
GET
/v1/rates
Get current FX rates for all supported networks
—

Webhooks

Receive real-time notifications when payout status changes. All webhook payloads are signed with HMAC-SHA256 so you can verify authenticity.

Event types

  • payout.createdPayout has been queued
  • payout.processingSent to network operator
  • payout.completedMobile money delivered
  • payout.failedPayout could not be completed
  • payout.refundedUSDC refunded to your balance
webhook-handler.ts
typescript
// Your webhook handler (Express.js example)
app.post('/webhooks/settlra', (req, res) => {
  const signature = req.headers['x-settlra-signature'];

  // Verify the webhook signature
  const event = Settlra.webhooks.constructEvent(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );

  switch (event.type) {
    case 'payout.completed':
      console.log('Payout delivered:', event.data.id);
      break;
    case 'payout.failed':
      console.log('Payout failed:', event.data.failure_reason);
      break;
  }

  res.json({ received: true });
});

Ready to build?

Get your API key and start in the sandbox — no credit card required.

Get API keyRead docs