Buy crypto with fiat into your PeerPesa balance

Use the buy endpoints to purchase cryptocurrency with fiat and credit it directly to your PeerPesa wallet balance. Buy is different from the onramp flow: buy credits your PeerPesa balance, while onramp delivers crypto to an external wallet. The flow is two steps: first request a locked quote with your desired fiat amount and payment method, then execute the quote. Quotes lock the rate and fees for exactly 30 minutes.

Sandbox
Production

Base URL: https://sandbox-api.peerpesa.co/v1

Base URL: https://api.peerpesa.co/v1

All requests require an Authorization: Bearer <token> header. POST endpoints also accept an optional Idempotency-Key header to prevent duplicate transactions. Amounts are decimal strings. Network codes are uppercase as returned by GET /currencies: STELLAR, CELO, BITCOIN.

Generate a buy quote

Request a quote for buying crypto with fiat. The returned quote is locked for 30 minutes.

Endpoint

POST /wallet/buy/quote

Request headers

string

required

Bearer token

string

Optional unique key to prevent duplicate quote creation

Request body

string

required

Crypto token to buy, e.g. USDC, USDT, BTC

string

required

Blockchain network, e.g. STELLAR, CELO, BITCOIN

string

required

Fiat currency to pay with, e.g. KES, TZS, NGN, ZAR, ZMW

string

required

Amount as a decimal string

string

required

Currency of the amount: fiat or crypto

string

required

Payment method: mobile_money or bank_transfer

Response fields

string

Quote ID, e.g. bq_...

string

Crypto symbol

string

Network code

string

Fiat currency used

string

Fiat amount to pay

string

Crypto amount you will receive

string

Exchange rate used (fiat per crypto unit)

object

Fee breakdown:

Show properties

string

Total fee in fiat

string

Fee currency (fiat)

string

Platform fee

string

Network fee

string

Payment method

string

ISO 8601 timestamp. Quote expires 30 minutes after created_at.

string

ISO 8601 timestamp

Example request

curl -X POST https://api.peerpesa.co/v1/wallet/buy/quote \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "USDC",
    "network": "STELLAR",
    "fiat_currency": "KES",
    "amount": "5000.00",
    "amount_currency": "fiat",
    "method": "mobile_money"
  }'

const res = await fetch("https://api.peerpesa.co/v1/wallet/buy/quote", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    symbol: "USDC",
    network: "STELLAR",
    fiat_currency: "KES",
    amount: "5000.00",
    amount_currency: "fiat",
    method: "mobile_money",
  }),
});
const data = await res.json();
console.log(data);

Example response

{
  "id": "bq_2vT8xKpQrLmN9wZc",
  "symbol": "USDC",
  "network": "STELLAR",
  "fiat_currency": "KES",
  "fiat_amount": "5000.00",
  "crypto_amount": "38.46153846",
  "rate": "130.00",
  "fee": {
    "total": "75.00",
    "currency": "KES",
    "app_fee": "50.00",
    "network_fee": "25.00"
  },
  "method": "mobile_money",
  "expires_at": "2024-01-15T14:30:00Z",
  "created_at": "2024-01-15T14:00:00Z"
}

Execute a buy

Execute a previously generated buy quote to create a pending buy transaction. Payment instructions are returned in the response.

Endpoint

POST /wallet/buy

Request headers

string

required

Bearer token

string

Optional unique key to prevent duplicate execution

Request body

string

required

ID of the buy quote to execute, e.g. bq_2vT8xKpQrLmN9wZc

object

Payer details. Required for mobile_money.

Show properties

string

Mobile money phone number (required for mobile_money)

string

Optional external reference string

Response fields

The response is a wallet transaction object with extra fields for payment instructions.

string

Transaction ID, e.g. txn_...

string

Always buy

string

pending until payment is received, then processing or completed

string

Crypto symbol

string

Network code

string

Crypto amount purchased

object

Fee breakdown as in the quote

string

Net crypto amount credited after fees

string

External reference if provided

string

On-chain transaction hash (null until completed)

object

Instructions for completing payment:

Show properties

string

mobile_money or bank_transfer

string

For mobile_money: STK push target number

string

For bank_transfer: bank account number

string

For bank_transfer: bank name

string

Payment reference to include

string

ISO 8601 timestamp

string

ISO 8601 timestamp

Example request

curl -X POST https://api.peerpesa.co/v1/wallet/buy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "bq_2vT8xKpQrLmN9wZc",
    "payer": {
      "phone_number": "+254712345678"
    },
    "reference": "order_12345"
  }'

const res = await fetch("https://api.peerpesa.co/v1/wallet/buy", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    quote_id: "bq_2vT8xKpQrLmN9wZc",
    payer: { phone_number: "+254712345678" },
    reference: "order_12345",
  }),
});
const data = await res.json();
console.log(data);

Example response

{
  "id": "txn_aBc3DeFg4HiJ5kL6",
  "type": "buy",
  "status": "pending",
  "symbol": "USDC",
  "network": "STELLAR",
  "amount": "38.46153846",
  "fee": {
    "total": "75.00",
    "currency": "KES",
    "app_fee": "50.00",
    "network_fee": "25.00"
  },
  "net_amount": "38.46153846",
  "reference": "order_12345",
  "tx_hash": null,
  "payment_instructions": {
    "method": "mobile_money",
    "phone_number": "+254712345678",
    "reference": "PPB123456"
  },
  "created_at": "2024-01-15T14:05:00Z",
  "updated_at": "2024-01-15T14:05:00Z"
}

After execution, complete the payment using the returned instructions. Your balance is credited once the payment is received. Track progress with GET /orders/{order_id} or listen for webhook events transaction.processing, transaction.completed, and transaction.failed.

Error codes

Code	Status	Meaning
`unsupported_network`	422	The requested network is not active or available for buying
`unsupported_asset`	422	The requested symbol/network combination is not supported
`amount_too_low`	422	The amount is below the minimum for this asset and network
`amount_too_high`	422	The amount exceeds the maximum for this asset and network
`quote_expired`	422	The quote expired after 30 minutes. Request a new quote
`insufficient_balance`	422	(Execute only) Your fiat balance is insufficient to cover the amount
`network_unavailable`	503	The target network is temporarily unavailable

Step-by-step flow

Request a quote

Call POST /wallet/buy/quote with your desired crypto, network, fiat amount, and payment method.

Review the quote

Check the rate, fee, and crypto_amount. The quote is valid for 30 minutes from created_at.

Execute the quote

Call POST /wallet/buy with the quote_id. Include payer.phone_number for mobile money.

Complete payment

Follow the payment_instructions in the response. Bank transfers require the provided reference.

Track completion

Poll GET /orders/{order_id} or wait for webhook events.

​Generate a buy quote

​Endpoint

​Request headers

​Request body

​Response fields

​Example request

​Example response

​Execute a buy

​Endpoint

​Request headers

​Request body

​Response fields

​Example request

​Example response

​Error codes

​Step-by-step flow

Generate a buy quote

Endpoint

Request headers

Request body

Response fields

Example request

Example response

Execute a buy

Endpoint

Request headers

Request body

Response fields

Example request

Example response

Error codes

Step-by-step flow