SettlraSettlra/Docs
DashboardAPI Playground

Quick Start

This guide walks you through making your first Settlra payout — from getting an API key to receiving a webhook confirmation. You'll be done in about 5 minutes.

1
Get API Key→
2
Create Quote→
3
Create Payout→
4
Monitor Webhook→
5
Check Status

Step 1: Get your API key

Sign up at dashboard.settlra.com to get your sandbox API key. Sandbox keys start with sk_sandbox_.

Set the key as an environment variable:

bash
"color:#ff7b72">export SETTLRA_API_KEY="sk_sandbox_your_key_here"

Step 2: Create a quote

A quote locks in the exchange rate for a USDC → local currency conversion. Quotes expire after 5 minutes, so create one right before initiating a payout.

Using curl

bash
"color:#ff7b72">curl "color:#79c0ff">-X POST https://api-sandbox.settlra.com/v1/quotes \
  "color:#79c0ff">-H "Authorization: Bearer $SETTLRA_API_KEY" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "source_amount_usdc": 100,
    "target_currency": "UGX",
    "idempotency_key": "quote-$(date +%s)"
  }'

Using Node.js

create-quote.jsjavascript
"color:#ff7b72">const response = "color:#ff7b72">await fetch('https://api-sandbox.settlra.com/v1/quotes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLRA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source_amount_usdc: 100,
    target_currency: 'UGX',
    idempotency_key: 'quote-' + Date.now(),
  }),
});

"color:#ff7b72">const quote = "color:#ff7b72">await response.json();
console.log(quote);
"color:#8b949e">// {
"color:#8b949e">//   quote_id: "q_01j3abc...",
"color:#8b949e">//   source_currency: "USDC",
"color:#8b949e">//   target_currency: "UGX",
"color:#8b949e">//   source_amount: 100,
"color:#8b949e">//   target_amount: 374250,
"color:#8b949e">//   exchange_rate: 3742.5,
"color:#8b949e">//   spread_percent: 0.01,
"color:#8b949e">//   status: "ACTIVE",
"color:#8b949e">//   expires_at: "2024-07-01T12:05:00.000Z"
"color:#8b949e">// }

Step 3: Create a payout

Use the quote_id from the previous step to create a payout. You'll receive a USDC deposit address — send the exact amount to trigger the payout.

In sandbox mode, you don't need to send real USDC. The sandbox automatically simulates a deposit and completes the payout.

Using curl

bash
"color:#ff7b72">curl "color:#79c0ff">-X POST https://api-sandbox.settlra.com/v1/payouts \
  "color:#79c0ff">-H "Authorization: Bearer $SETTLRA_API_KEY" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "quote_id": "q_01j3abc...",
    "recipient_phone": "+256700123456",
    "recipient_name": "Jane Nakato",
    "network": "MTN_UG",
    "idempotency_key": "payout-$(date +%s)"
  }'

Using Node.js

create-payout.jsjavascript
"color:#ff7b72">const response = "color:#ff7b72">await fetch('https://api-sandbox.settlra.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SETTLRA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quote_id: quote.quote_id,
    recipient_phone: '+256700123456',
    recipient_name: 'Jane Nakato',
    network: 'MTN_UG',
    idempotency_key: 'payout-' + Date.now(),
  }),
});

"color:#ff7b72">const payout = "color:#ff7b72">await response.json();
console.log(payout);
"color:#8b949e">// {
"color:#8b949e">//   payout_id: "pyt_01j3xyz...",
"color:#8b949e">//   status: "AWAITING_FUNDS",
"color:#8b949e">//   deposit_address: "0xABCD1234...",
"color:#8b949e">//   source_amount_usdc: 100,
"color:#8b949e">//   target_amount_fiat: 374250,
"color:#8b949e">//   target_currency: "UGX",
"color:#8b949e">//   exchange_rate: 3742.5,
"color:#8b949e">//   recipient_phone: "+256700123456",
"color:#8b949e">//   network: "MTN_UG",
"color:#8b949e">//   message: "Send exactly 100.000000 USDC to 0xABCD1234... to initiate this payout."
"color:#8b949e">// }

Step 4: Monitor via webhook

Configure a webhook endpoint in your dashboard to receive real-time notifications when payout status changes.

Example webhook handler (Express.js)

webhook-handler.jsjavascript
"color:#ff7b72">import express "color:#ff7b72">from 'express';
"color:#ff7b72">import crypto "color:#ff7b72">from 'crypto';

"color:#ff7b72">const app = express();
app.use(express.raw({ "color:#ff7b72">type: 'application/json' }));

app.post('/webhooks/settlra', (req, res) => {
  "color:#8b949e">// Verify signature
  "color:#ff7b72">const signature = req.headers['x-settlra-signature'];
  "color:#ff7b72">const expectedSig = crypto
    .createHmac('sha256', process.env.SETTLRA_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  "color:#ff7b72">if (signature !== `sha256=${expectedSig}`) {
    "color:#ff7b72">return res.status(401).send('Invalid signature');
  }

  "color:#ff7b72">const event = JSON.parse(req.body.toString());

  switch (event."color:#ff7b72">type) {
    case 'payout.settled':
      console.log('Payout delivered:', event.data.payout_id);
      "color:#8b949e">// Update your DB, notify your user, etc.
      break;
    case 'payout.failed':
      console.error('Payout failed:', event.data.failure_reason);
      break;
  }

  res.status(200).json({ received: "color:#79c0ff">true });
});

Step 5: Check payout status

You can also poll the status at any time using the payout ID from step 3.

bash
"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/payouts/pyt_01j3xyz... \
  "color:#79c0ff">-H "Authorization: Bearer $SETTLRA_API_KEY"
json
{
  "payout_id": "pyt_01j3xyz...",
  "status": "SETTLED",
  "source_amount_usdc": 100,
  "target_amount_fiat": 374250,
  "target_currency": "UGX",
  "exchange_rate": 3742.5,
  "recipient_phone": "+256700123456",
  "network": "MTN_UG",
  "settled_at": "2024-07-01T12:04:35.000Z",
  "created_at": "2024-07-01T12:01:00.000Z"
}

Next steps