Skip to main content

Fiat APIs

Fiat APIs

The Fiat API provides endpoints to initiate deposits, withdrawals, and balance lookups across supported currencies and payment channels. All endpoints are authenticated using your API key and HMAC signature, as detailed in the Authentication & Security section.

Overview​

All fiat endpoints are served under:

https://api.keshflippay.com/api/v1/fiat

These APIs are designed for integrating traditional (non-crypto) payment flows, including card payments, mobile money, and bank transfers.

1. Create Deposit Request​

Used to initiate a deposit into your keshflippay partner account.

Endpoint
POST /api/v1/fiat/deposits

Headers

NameDescription
X-keshflippay-KeyYour public API key
X-keshflippay-TimestampCurrent UNIX timestamp
X-keshflippay-SignatureHMAC-SHA256 signature
Content-Typeapplication/json

Request Example

{
  "partnerId": "partner_001",
  "currency": "USD",
  "amount": 500,
  "channel": "bank_transfer",
  "reference": "order_001",
  "idempotencyKey": "deposit_001"
}

cURL Example

Terminal
curl -X POST "https://api.keshflippay.com/api/v1/fiat/deposits" \
-H "Content-Type: application/json" \
-H "X-keshflippay-Key: <api_key>" \
-H "X-keshflippay-Timestamp: $(date +%s)" \
-H "X-keshflippay-Signature: <signature>" \
-d '{"partnerId":"partner_001","currency":"USD","amount":500,"channel":"bank_transfer","reference":"order_001"}'

Response Example

{
  "status": "success",
  "data": {
    "depositId": "dep_001",
    "currency": "USD",
    "amount": 500,
    "status": "PENDING",
    "paymentInstructions": {
      "bankName": "ABC Bank",
      "accountNumber": "123456789",
      "accountName": "keshflippay Partner Deposit",
      "reference": "order_001"
    }
  },
  "message": "Deposit created successfully."
}

2. Get Deposit Details​

Retrieve details for a specific deposit.

Endpoint GET /api/v1/fiat/deposits/:id

Response Example

{
  "status": "success",
  "data": {
    "depositId": "dep_001",
    "currency": "USD",
    "amount": 500,
    "status": "COMPLETED",
    "confirmedAt": "2025-10-12T13:45:00Z",
    "reference": "order_001"
  }
}

3. List Deposits​

Retrieve all deposits made by your partner account, with optional filters.

Endpoint GET /api/v1/fiat/deposits

Query Parameters

ParameterDescription
statusFilter by status (e.g. PENDING, COMPLETED)
currencyFilter by currency code (e.g. USD)
limitNumber of results to return (default: 20)

Response Example

{
  "status": "success",
  "data": [
    {
      "depositId": "dep_001",
      "amount": 500,
      "currency": "USD",
      "status": "COMPLETED"
    },
    {
      "depositId": "dep_002",
      "amount": 300,
      "currency": "EUR",
      "status": "PENDING"
    }
  ]
}

4. Create Withdrawal Request​

Initiate a withdrawal from your available balance.

Endpoint POST /api/v1/fiat/withdrawals

Request Example

{
  "partnerId": "partner_001",
  "currency": "USD",
  "amount": 250,
  "destination": {
    "type": "bank_account",
    "accountName": "John Doe",
    "accountNumber": "987654321",
    "bankName": "ABC Bank"
  },
  "reference": "withdrawal_001",
  "idempotencyKey": "wd_001"
}

Response Example

{
  "status": "success",
  "data": {
    "withdrawalId": "wd_001",
    "currency": "USD",
    "amount": 250,
    "status": "PENDING",
    "createdAt": "2025-10-12T14:00:00Z"
  },
  "message": "Withdrawal created successfully."
}

5. Get Withdrawal Details​

Retrieve information about a specific withdrawal.

Endpoint GET /api/v1/fiat/withdrawals/:id

Response Example

{
  "status": "success",
  "data": {
    "withdrawalId": "wd_001",
    "currency": "USD",
    "amount": 250,
    "status": "COMPLETED",
    "completedAt": "2025-10-12T16:10:00Z",
    "reference": "withdrawal_001"
  }
}

6. List Withdrawals​

Retrieve all fiat withdrawals associated with your partner account.

Endpoint GET /api/v1/fiat/withdrawals

Response Example

{
  "status": "success",
  "data": [
    {
      "withdrawalId": "wd_001",
      "currency": "USD",
      "amount": 250,
      "status": "COMPLETED"
    },
    {
      "withdrawalId": "wd_002",
      "currency": "EUR",
      "amount": 120,
      "status": "PENDING"
    }
  ]
}

7. Check Balance​

Retrieve your current fiat balances for supported currencies.

Endpoint GET /api/v1/fiat/balances/:partnerId

Response Example

{
  "status": "success",
  "data": [
    {
      "currency": "USD",
      "available": 12500,
      "locked": 500
    },
    {
      "currency": "EUR",
      "available": 8200,
      "locked": 200
    }
  ]
}

8. Supported Currencies​

Retrieve a list of currencies available for fiat transactions.

Endpoint GET /api/v1/fiat/currencies

Response Example

{
  "status": "success",
  "data": [
    { "code": "USD", "name": "United States Dollar" },
    { "code": "EUR", "name": "Euro" },
    { "code": "GBP", "name": "British Pound Sterling" },
    { "code": "KES", "name": "Kenyan Shilling" }
  ]
}

Error Handling​

All fiat endpoints follow the same standard response format:

FieldDescription
status"success" or "error"
dataObject or list containing the payload
messageHuman-readable context message

For example:

{
  "status": "error",
  "message": "Insufficient balance for withdrawal."
}

Refer to Error Codes for the full list.

Rate Limits​

Every endpoint is rate-limited to ensure fair usage.

HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetTimestamp for reset