Base URL https://sandbox.fiatsend.com

Demo API Key fs_sandbox_demo_key_2026

Getting Started

Fiatsend Partner API

Enable instant stablecoin-to-mobile-money payouts for your users in Africa. Convert USDC and USDT to Ghana Cedis and deliver funds directly to MTN MoMo, Telecel Cash, and AirtelTigo Money wallets in seconds.

Instant Conversion

Sub-10-second settlement from stablecoin to mobile money wallet.

3 Mobile Networks

MTN MoMo, Telecel Cash, and AirtelTigo Money across Ghana.

On-Chain Verification

Every transaction is anchored on-chain with a verifiable hash.

Real-Time Webhooks

Get instant status callbacks for every withdrawal state change.

Base URLs

Environment	Base URL
Sandbox	`https://sandbox.fiatsend.com/v1`
Production	`https://api.fiatsend.com/v1`

Rate Limits

Plan	Requests / min	Requests / day
Sandbox	60	10,000
Production	300	100,000

Security

Authentication

All API requests require a Bearer token in the Authorization header. API keys are issued during partner onboarding.

HTTP Header

Authorization: Bearer your_api_key_here

Getting API Keys

Contact partners@fiatsend.com to request sandbox and production API keys. You'll receive a key pair (public + secret) during onboarding.

Example Request

bash

curl -X GET "https://sandbox.fiatsend.com/v1/health" \
  -H "Authorization: Bearer fs_test_abc123..."

javascript

const response = await fetch("https://sandbox.fiatsend.com/v1/health", {
  headers: {
    "Authorization": "Bearer fs_test_abc123...",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

Tutorial

Quick Start

Follow these five steps to make your first stablecoin-to-mobile-money payout.

1

Get API Credentials

Contact partners@fiatsend.com to receive your sandbox API key. You'll get a key pair for testing.

2

Check Supported Networks

Query the available mobile money networks and their current status.

bash

curl -X GET "https://sandbox.fiatsend.com/v1/supported-networks" \
  -H "Authorization: Bearer fs_test_abc123..."

javascript

const res = await fetch("https://sandbox.fiatsend.com/v1/supported-networks", {
  headers: { "Authorization": "Bearer fs_test_abc123..." }
});
const { data } = await res.json();
console.log(data);
// [{ network_id: "MTN", name: "MTN MoMo", status: "operational", ... }]

3

Get a Rate Quote

Check the current FX rate before creating a withdrawal. Rates are guaranteed until valid_until.

bash

curl -X GET "https://sandbox.fiatsend.com/v1/rates?from_currency=USDC&to_currency=GHS&amount=100.00" \
  -H "Authorization: Bearer fs_test_abc123..."

javascript

const params = new URLSearchParams({
  from_currency: "USDC",
  to_currency: "GHS",
  amount: "100.00"
});

const res = await fetch(`https://sandbox.fiatsend.com/v1/rates?${params}`, {
  headers: { "Authorization": "Bearer fs_test_abc123..." }
});
const { data } = await res.json();
console.log(`Rate: ${data.rate} GHS per USDC, valid until ${data.valid_until}`);

4

Create a Withdrawal

Initiate the payout. Fiatsend locks the rate, converts USDC to GHS, and sends funds to the mobile wallet.

bash

curl -X POST "https://sandbox.fiatsend.com/v1/withdrawals" \
  -H "Authorization: Bearer fs_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50.00",
    "currency": "USDC",
    "recipient_phone": "+233241234567",
    "mobile_network": "MTN",
    "reference_id": "deel-txn-abc123",
    "metadata": {
      "contractor_id": "con_12345",
      "invoice_id": "inv_67890"
    }
  }'

javascript

const res = await fetch("https://sandbox.fiatsend.com/v1/withdrawals", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fs_test_abc123...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: "50.00",
    currency: "USDC",
    recipient_phone: "+233241234567",
    mobile_network: "MTN",
    reference_id: "deel-txn-abc123",
    metadata: {
      contractor_id: "con_12345",
      invoice_id: "inv_67890"
    }
  })
});

const { data } = await res.json();
console.log(`Withdrawal ${data.withdrawal_id} created — status: ${data.status}`);

5

Handle the Webhook Callback

Fiatsend sends a POST request to your registered webhook URL when the withdrawal status changes. See Webhooks for details.

json

{
  "event": "withdrawal.completed",
  "timestamp": "2026-03-21T06:59:42Z",
  "data": {
    "withdrawal_id": "wd_9f8e7d6c5b4a",
    "status": "completed",
    "amount": "50.00",
    "currency": "USDC",
    "ghs_amount": "750.00",
    "recipient_phone": "+233241234567",
    "mobile_network": "MTN",
    "reference_id": "deel-txn-abc123"
  }
}

API Reference

Withdrawals

Create and manage stablecoin-to-mobile-money withdrawals.

POST /v1/withdrawals

Create a withdrawal

Initiate a stablecoin-to-mobile-money withdrawal. Fiatsend locks the FX rate at the time of request, converts the stablecoin amount to GHS, and delivers funds to the specified mobile money wallet.

The withdrawal goes through the following statuses:

pending — Request received, awaiting processing
processing — On-chain transaction submitted, mobile money transfer initiated
completed — Funds delivered to mobile money wallet
failed — Transaction failed (funds returned to source)

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Amount in source currency (e.g., "50.00")
`currency`	string	Yes	Source stablecoin: `USDC` or `USDT`
`recipient_phone`	string	Yes	Recipient's phone in E.164 format (e.g., +233241234567)
`mobile_network`	string	Yes	`MTN`, `TELECEL`, or `AIRTELTIGO`
`reference_id`	string	Yes	Your unique transaction reference (idempotency key)
`metadata`	object	No	Optional key-value metadata

Request

json

{
  "amount": "50.00",
  "currency": "USDC",
  "recipient_phone": "+233241234567",
  "mobile_network": "MTN",
  "reference_id": "deel-txn-abc123",
  "metadata": {
    "contractor_id": "con_12345",
    "invoice_id": "inv_67890"
  }
}

Response 201

json

{
  "status": "success",
  "data": {
    "withdrawal_id": "wd_9f8e7d6c5b4a",
    "status": "pending",
    "amount": "50.00",
    "currency": "USDC",
    "ghs_amount": "750.00",
    "fx_rate": "15.00",
    "fee": "0.50",
    "recipient_phone": "+233241234567",
    "mobile_network": "MTN",
    "reference_id": "deel-txn-abc123",
    "estimated_completion": "2026-03-21T07:00:00Z",
    "created_at": "2026-03-21T06:59:30Z"
  }
}

Error Response 400

json

{
  "status": "error",
  "code": "INVALID_PHONE",
  "message": "Phone number must be a valid Ghana number starting with +233"
}

GET /v1/withdrawals/{withdrawal_id}

Get withdrawal status

Retrieve the current status and details of a withdrawal. For real-time updates, we recommend using webhooks instead of polling.

Path Parameters

Parameter	Type	Required	Description
`withdrawal_id`	string	Yes	The withdrawal ID (e.g., `wd_9f8e7d6c5b4a`)

Response 200

json

{
  "status": "success",
  "data": {
    "withdrawal_id": "wd_9f8e7d6c5b4a",
    "status": "completed",
    "amount": "50.00",
    "currency": "USDC",
    "ghs_amount": "750.00",
    "fx_rate": "15.00",
    "fee": "0.50",
    "recipient_phone": "+233241234567",
    "mobile_network": "MTN",
    "reference_id": "deel-txn-abc123",
    "on_chain_tx_hash": "0x1234abcd...",
    "mobile_money_reference": "MOMO-REF-456789",
    "created_at": "2026-03-21T06:59:30Z",
    "processing_at": "2026-03-21T06:59:35Z",
    "completed_at": "2026-03-21T06:59:42Z"
  }
}

GET /v1/transactions

List transactions

Retrieve a paginated list of transactions with optional filters.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `pending`, `processing`, `completed`, `failed`
`from_date`	date-time	No	Start date filter (ISO 8601)
`to_date`	date-time	No	End date filter (ISO 8601)
`reference_id`	string	No	Filter by your reference ID
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Results per page (default: 25, max: 100)

Response 200

json

{
  "status": "success",
  "data": [
    {
      "withdrawal_id": "wd_9f8e7d6c5b4a",
      "status": "completed",
      "amount": "50.00",
      "currency": "USDC",
      "ghs_amount": "750.00",
      "fx_rate": "15.00",
      "recipient_phone": "+233241234567",
      "mobile_network": "MTN",
      "reference_id": "deel-txn-abc123",
      "created_at": "2026-03-21T06:59:30Z",
      "completed_at": "2026-03-21T06:59:42Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

API Reference

Rates

Get real-time FX rates for stablecoin to GHS conversion.

GET /v1/rates

Get current FX rate

Get a real-time quote for converting stablecoins to GHS. The returned rate includes a valid_until timestamp — the rate is guaranteed until that time.

Query Parameters

Parameter	Type	Required	Description
`from_currency`	string	Yes	`USDC` or `USDT`
`to_currency`	string	Yes	`GHS`
`amount`	string	Yes	Amount in source currency (e.g., "100.00")

Response 200

json

{
  "status": "success",
  "data": {
    "from_currency": "USDC",
    "to_currency": "GHS",
    "amount": "100.00",
    "rate": "15.02",
    "fee": "1.00",
    "total_ghs": "1501.00",
    "valid_until": "2026-03-21T07:05:00Z"
  }
}

API Reference

Networks

Query supported mobile money networks and their status.

GET /v1/supported-networks

List supported networks

Returns all available mobile money networks with their current operational status.

Response 200

json

{
  "status": "success",
  "data": [
    {
      "network_id": "MTN",
      "name": "MTN MoMo",
      "country": "GH",
      "currency": "GHS",
      "status": "operational",
      "min_amount": "5.00",
      "max_amount": "10000.00"
    },
    {
      "network_id": "TELECEL",
      "name": "Telecel Cash",
      "country": "GH",
      "currency": "GHS",
      "status": "operational",
      "min_amount": "5.00",
      "max_amount": "5000.00"
    },
    {
      "network_id": "AIRTELTIGO",
      "name": "AirtelTigo Money",
      "country": "GH",
      "currency": "GHS",
      "status": "operational",
      "min_amount": "5.00",
      "max_amount": "5000.00"
    }
  ]
}

GET /v1/limits

Get transaction limits

Returns transaction limits per KYC tier.

Response 200

json

{
  "status": "success",
  "data": [
    {
      "tier": "basic",
      "daily_limit": "500.00",
      "monthly_limit": "5000.00",
      "per_transaction_max": "200.00"
    },
    {
      "tier": "verified",
      "daily_limit": "5000.00",
      "monthly_limit": "50000.00",
      "per_transaction_max": "2000.00"
    },
    {
      "tier": "enterprise",
      "daily_limit": "50000.00",
      "monthly_limit": "500000.00",
      "per_transaction_max": "10000.00"
    }
  ]
}

API Reference

Webhook Endpoints

Register and manage webhook endpoints for status callbacks.

POST /v1/webhooks

Register a webhook

Register a URL to receive real-time status updates for withdrawals. All webhook payloads are signed with HMAC-SHA256.

Request Body

Field	Type	Required	Description
`url`	string (URI)	Yes	Your webhook endpoint URL
`events`	string[]	Yes	Events to subscribe to
`secret`	string	Yes	Secret for HMAC-SHA256 signature verification

Request

json

{
  "url": "https://api.deel.com/webhooks/fiatsend",
  "events": [
    "withdrawal.completed",
    "withdrawal.failed",
    "withdrawal.processing"
  ],
  "secret": "whsec_your_secret_here"
}

Response 201

json

{
  "status": "success",
  "data": {
    "webhook_id": "wh_abc123",
    "url": "https://api.deel.com/webhooks/fiatsend",
    "events": ["withdrawal.completed", "withdrawal.failed", "withdrawal.processing"],
    "active": true,
    "created_at": "2026-03-21T07:00:00Z"
  }
}

GET /v1/webhooks

List registered webhooks

Retrieve all webhook endpoints registered for your account.

Response 200

json

{
  "status": "success",
  "data": [
    {
      "webhook_id": "wh_abc123",
      "url": "https://api.deel.com/webhooks/fiatsend",
      "events": ["withdrawal.completed", "withdrawal.failed"],
      "active": true,
      "created_at": "2026-03-21T07:00:00Z"
    }
  ]
}

DELETE /v1/webhooks/{webhook_id}

Delete a webhook

Remove a registered webhook endpoint.

Path Parameters

Parameter	Type	Required	Description
`webhook_id`	string	Yes	The webhook ID to delete

Response 204

No content — webhook successfully deleted.

Register a webhook with POST /v1/webhooks above, then delete it here using the last registered webhook_id.

API Reference

Health

Service health and status checks. This endpoint does not require authentication.

GET /v1/health

Service health check

Returns service status, uptime, and API version. No authentication required.

Response 200

json

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 864000,
  "environment": "sandbox",
  "services": {
    "blockchain": "operational",
    "mobile_money": "operational",
    "database": "operational"
  }
}

Guide

Webhooks

Fiatsend sends real-time notifications to your server when withdrawal statuses change. Instead of polling the API, register a webhook URL and we'll push updates to you.

How It Works

Register a webhook endpoint via POST /v1/webhooks
Fiatsend sends a POST request to your URL whenever a subscribed event occurs
Your server verifies the signature and processes the event
Respond with a 2xx status code to acknowledge receipt

Retry Policy

If your endpoint returns a non-2xx status or times out (30s), Fiatsend retries with exponential backoff: 1 min, 5 min, 30 min, 2 hr, 24 hr. After 5 failed attempts, the webhook is marked as failed.

Webhook Payload

json

{
  "event": "withdrawal.completed",
  "timestamp": "2026-03-21T06:59:42Z",
  "data": {
    "withdrawal_id": "wd_9f8e7d6c5b4a",
    "status": "completed",
    "amount": "50.00",
    "currency": "USDC",
    "ghs_amount": "750.00",
    "fx_rate": "15.00",
    "fee": "0.50",
    "recipient_phone": "+233241234567",
    "mobile_network": "MTN",
    "reference_id": "deel-txn-abc123",
    "on_chain_tx_hash": "0x1234abcd...",
    "mobile_money_reference": "MOMO-REF-456789",
    "completed_at": "2026-03-21T06:59:42Z"
  }
}

Signature Verification

Every webhook request includes an X-Fiatsend-Signature header containing an HMAC-SHA256 signature of the request body, computed using your webhook secret. Always verify this signature before processing events.

javascript

const crypto = require('crypto');

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

// Express middleware example
app.post('/webhooks/fiatsend', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-fiatsend-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  
  switch (event.event) {
    case 'withdrawal.completed':
      // Mark payout as complete in your system
      break;
    case 'withdrawal.failed':
      // Handle failure, notify user
      break;
  }

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

Event Types

Event	Description
`withdrawal.pending`	Withdrawal request received, awaiting processing
`withdrawal.processing`	On-chain transaction submitted, mobile money transfer initiated
`withdrawal.completed`	Funds successfully delivered to mobile money wallet
`withdrawal.failed`	Transaction failed — funds returned to source

Reference

Error Codes

All error responses follow a consistent format with a machine-readable code and human-readable message.

json

{
  "status": "error",
  "code": "INVALID_PHONE",
  "message": "Phone number must be a valid Ghana number starting with +233"
}

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`INVALID_PHONE`	400	Invalid phone number format
`INVALID_NETWORK`	400	Unsupported mobile money network
`BELOW_MINIMUM`	422	Amount below minimum threshold
`ABOVE_MAXIMUM`	422	Amount above maximum threshold
`RATE_EXPIRED`	422	Quoted rate has expired
`NETWORK_DOWN`	503	Mobile money network unavailable
`INSUFFICIENT_LIQUIDITY`	503	Insufficient liquidity for conversion
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error

Resources

SDKs & Tools

Libraries and tools to accelerate your integration.

Node.js SDK

npm install @fiatsend/sdk Coming Soon

Python SDK

pip install fiatsend Coming Soon

Postman Collection

Import our collection to test all endpoints.

Download Collection

OpenAPI Spec

Full API specification in OpenAPI 3.0 format.

Download YAML

Help

Support

Need help integrating? Our engineering team is here to support you.

Email

partners@fiatsend.com

Website

fiatsend.com

Status Page

status.fiatsend.com Coming Soon

Live Sandbox API

Fiatsend Partner API

Instant Conversion

3 Mobile Networks

On-Chain Verification

Real-Time Webhooks

Base URLs

Rate Limits

Authentication

Example Request

Quick Start

Get API Credentials

Check Supported Networks

Get a Rate Quote

Create a Withdrawal

Handle the Webhook Callback

Withdrawals

Create a withdrawal

Request Body

Request

Response 201

Error Response 400

Get withdrawal status

Path Parameters

Response 200

List transactions

Query Parameters

Response 200

Rates

Get current FX rate

Query Parameters

Response 200

Networks

List supported networks

Response 200

Get transaction limits

Response 200

Webhook Endpoints

Register a webhook

Request Body

Request

Response 201

List registered webhooks

Response 200

Delete a webhook

Path Parameters

Response 204

Health

Service health check

Response 200

Webhooks

How It Works

Webhook Payload

Signature Verification

Event Types

Error Codes

SDKs & Tools

Node.js SDK

Python SDK

Postman Collection

OpenAPI Spec

Support

Email

Website

Status Page