Skip to content

Developer Documentation

Payments & Transfers

Unified endpoints for moving money within and outside the Nexbit ecosystem.

Internal Transfer (P2P)

POST /v1/payments/transfer

Instantly transfer funds between any two Nexbit wallets. Cross-currency transfers will automatically apply the latest FX rate.

Request Body
{
  "from_wallet": 101,
  "to_wallet": 102,
  "amount": "50.00",
  "currency": "KES",
  "metadata": {
    "note": "For lunch"
  }
}
Body Parameters
  • from_wallet (integer, required): The ID of the sender's wallet.
  • to_wallet (integer, required): The ID of the recipient's wallet.
  • amount (string, required): The amount to transfer.
  • currency (string, required): The currency code of the amount.
  • metadata (object, optional): Additional key-value pairs for context.
Test Request
Response
{
  "status": "success",
  "data": {
    "tx_id": "10056",
    "status": "SETTLED",
    "risk_score": 0.05,
    "rules_applied": [
      "FraudCheck: ALLOW"
    ],
    "error": null,
    "timestamp": "2025-10-26T12:00:00+03:00"
  }
}

Deposit (Money In)

POST /v1/payments/transact

Initiate a deposit from an external payment gateway like M-Pesa. This will trigger an STK push to the provided phone number.

Request Body
{
  "type": "deposit",
  "amount": 100,
  "currency": "KES",
  "phone_number": "254712345678"
}
Body Parameters
  • type (string, required): Must be 'deposit'.
  • amount (number, required): The amount to deposit.
  • currency (string, required): The currency code.
  • phone_number (string, optional): The phone number for mobile money push (if applicable).
Test Request
Response
{
  "success": true,
  "status": "initiated",
  "provider_ref": "ws_CO_DERR_1234567890",
  "redirect_url": null,
  "message": "Deposit initiated successfully. Please complete the payment on your device."
}

Withdrawal (Payout)

POST /v1/payments/transact

Withdraw funds from a Nexbit wallet to an external destination, such as a bank account or mobile money number.

Request Body
{
  "type": "withdrawal",
  "from_wallet": 101,
  "amount": 2500,
  "currency": "KES",
  "destination": "254712345678",
  "metadata": {
    "gateway": "mpesa"
  }
}
Body Parameters
  • type (string, required): Must be 'withdrawal'.
  • from_wallet (integer, required): The source wallet ID.
  • amount (number, required): The amount to withdraw.
  • currency (string, required): The currency code.
  • destination (string, required): The external account identifier (e.g., phone number, bank account).
  • metadata (object, optional): Gateway-specific parameters.
Test Request
Response
{
  "status": "success",
  "data": {
    "tx_id": "10057",
    "status": "SETTLED",
    "risk_score": 0.1,
    "rules_applied": [
      "FraudCheck: ALLOW"
    ],
    "error": null,
    "timestamp": "2025-10-26T12:05:00+03:00"
  }
}

Async Payment

POST /v1/payments/async

Queue a payment for background processing. This is ideal for high-volume or non-time-sensitive transactions, as it returns a job ID immediately.

Request Body
{
  "from_wallet": 101,
  "to_wallet": 102,
  "amount": "1.00",
  "currency": "KES"
}
Body Parameters
  • from_wallet (integer, required): The sender wallet ID.
  • to_wallet (integer, required): The recipient wallet ID.
  • amount (string, required): The amount to transfer.
  • currency (string, required): The currency code.
Test Request
Response (202 Accepted)
{
  "status": "accepted",
  "job_id": "job_a1b2c3d4e5f6",
  "message": "Transaction queued for processing."
}