API Reference
Index

API Reference

Fiatsend provides simple APIs for integrating instant global payments into your applications.

Installation

npm install @fiatsend/sdk
import Fiatsend from "@fiatsend/sdk";
 
const fiatsend = new Fiatsend({
  apiKey: "your-api-key",
  environment: "testnet"
});

Core Endpoints

Payment Processing

POST /payments/initiate
GET /payments/{id}
POST /payments/request-address

Identity Management

POST /identity/mint
GET /identity/resolve/{phone}
GET /identity/check/{phone}

Wallet Operations

GET /wallet/balance/{address}
GET /wallet/transactions
POST /wallet/withdraw

Mobile Money

POST /mobile-money/mtn
POST /mobile-money/airtel
POST /mobile-money/telecel

Exchange Rates

GET /rates
GET /rates/{pair}

API Key Management

POST /api-keys
GET /api-keys
DELETE /api-keys/{id}

Common Operations

Initiate Payment

const payment = await sdk.payment.initiatePayment({
  amount: 100,
  currency: "USDT",
  recipient: "+233551234567",
  description: "Payment for services",
  country: "GH"
});
 
console.log("Payment ID:", payment.transactionId);
console.log("Status:", payment.status);

Get Wallet Balance

const balance = await sdk.wallet.getBalance("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
console.log("GHSFIAT Balance:", balance.balances.GHSFIAT?.balance);
console.log("USDT Balance:", balance.balances.USDT?.balance);

Resolve Mobile Number

const resolution = await sdk.identity.resolvePhoneToAddress("+233551234567");
console.log("Wallet Address:", resolution.wallet);
console.log("Has Identity NFT:", resolution.hasIdentity);

Create Payment Request

const request = await sdk.payment.generateRequestAddress({
  amount: 50,
  currency: "USDT",
  description: "Order #12345",
  merchantId: "merchant_123",
  callbackUrl: "https://your-app.com/webhook/payment"
});
 
console.log("Payment Address:", request.address);
console.log("QR Code:", request.qrCode);

Mobile Money Payment

const mtnPayment = await sdk.payment.createMTNPayment({
  amount: 100,
  phoneNumber: "0551234567",
  externalRef: "PAY-12345",
  wallet: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
});
 
console.log("MTN Payment ID:", mtnPayment.paymentId);

Get Transaction History

const transactions = await sdk.wallet.getTransactions({
  walletAddress: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  page: 1,
  limit: 20
});
 
console.log("Total Transactions:", transactions.total);
transactions.data.forEach(tx => {
  console.log(`${tx.type}: ${tx.amount} ${tx.currency} - ${tx.status}`);
});

API Info

EnvironmentBase URLAuthentication
Testnethttps://api-testnet.fiatsend.networkAPI Key
Mainnethttps://api.fiatsend.networkAPI Key

Authentication:

headers: {
  'Authorization': 'Bearer your-api-key',
  'Content-Type': 'application/json'
}

Error Handling

The Fiatsend API uses standard HTTP status codes and returns detailed error information:

Common Error Codes

Status CodeError TypeDescription
400BAD_REQUESTInvalid request parameters
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENInsufficient permissions
404NOT_FOUNDResource not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid phone number format",
    "details": {
      "field": "recipient",
      "value": "123456789",
      "expected": "E.164 format (+233551234567)"
    }
  }
}

Error Handling Example

try {
  const payment = await sdk.payment.initiatePayment({
    amount: 100,
    currency: "USDT",
    recipient: "invalid-phone",
    country: "GH"
  });
} catch (error) {
  if (error.status === 400) {
    console.error("Invalid request:", error.message);
    // Handle validation errors
  } else if (error.status === 401) {
    console.error("Authentication failed:", error.message);
    // Handle authentication errors
  } else if (error.status === 429) {
    console.error("Rate limited:", error.message);
    // Handle rate limiting
  } else {
    console.error("Unexpected error:", error.message);
    // Handle other errors
  }
}

Rate Limits

API requests are rate limited to ensure fair usage:

Endpoint TypeLimitWindow
Payment Operations100 requests1 minute
Wallet Operations200 requests1 minute
Identity Operations50 requests1 minute
General API1000 requests1 minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Webhooks

Fiatsend can send webhooks to notify your application of important events:

Supported Events

  • payment.completed - Payment successfully processed
  • payment.failed - Payment failed
  • withdrawal.completed - Withdrawal completed
  • withdrawal.failed - Withdrawal failed
  • identity.verified - Identity verification completed

Webhook Security

Webhooks are signed with HMAC-SHA256 for verification:

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === expectedSignature;
}
 
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-fiatsend-signature'];
  const payload = JSON.stringify(req.body);
  
  if (verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    // Process webhook
    console.log('Webhook verified:', req.body);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Unauthorized');
  }
});

Need Help?

Use CasesAddresses