Convert fiat to crypto with PeerPesa onramp

An onramp converts local fiat into cryptocurrency. After you create a quote that locks the rate and fees, you confirm the quote with the wallet address that will receive the crypto and the payer details. The transaction moves through statuses as fiat is collected and crypto is sent.

Check the rate

Call GET /rates with type=onramp and your preferred network, asset, and fiat_currency to see the current indicative rate.

Create a quote

Call POST /quotes to lock the rate and fee breakdown for 30 minutes. Save the quote id.

Confirm the quote

Call POST /quotes/{id}/confirm with the destination wallet_address and payer details. You receive a transaction in status awaiting_payment with payment_instructions.

Track the transaction

Poll GET /orders/{order_id} or wait for webhooks. Status flows from awaiting_payment to processing, then completed or failed.

Confirm an onramp quote

POST /quotes/{id}/confirm Confirms an active onramp quote and creates the onramp transaction.

Path parameters

string

required

Active onramp quote ID from POST /quotes. Valid for 30 minutes.

Request body

string

required

Blockchain address that will receive the crypto.

object

required

Payer details. For mobile_money, include phone_number. For bank_transfer, include account details such as account_number and bank_code.

string

Optional external reference ID for your records.

Request

curl -X POST https://api.peerpesa.co/v1/quotes/qt_8f2k3m9n1p0q/confirm \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "GABC123...",
    "payer": {
      "phone_number": "+254712345678"
    },
    "reference": "order-12345"
  }'

const response = await fetch('https://api.peerpesa.co/v1/quotes/qt_8f2k3m9n1p0q/confirm', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <access_token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    wallet_address: 'GABC123...',
    payer: {
      phone_number: '+254712345678'
    },
    reference: 'order-12345'
  })
});

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

Response

{
  "id": "txn_9a3b4c5d6e7f",
  "type": "onramp",
  "status": "awaiting_payment",
  "quote_id": "qt_8f2k3m9n1p0q",
  "network": "stellar",
  "asset": "USDC",
  "fiat_currency": "KES",
  "source_amount": "100.00",
  "destination_amount": "0.76",
  "fee": {
    "total": "1.50",
    "currency": "USDC",
    "processing_fee": "1.00",
    "network_fee": "0.50"
  },
  "rate": "129.45",
  "tx_hash": null,
  "wallet_address": "GABC123...",
  "reference": "order-12345",
  "payment_instructions": {
    "method": "mobile_money",
    "phone_number": "+254712345678",
    "prompt_text": "You will receive an M-Pesa prompt to complete payment."
  },
  "created_at": "2024-01-15T10:05:00Z",
  "updated_at": "2024-01-15T10:05:00Z"
}

Response fields

string

Unique transaction identifier, e.g. txn_....

string

Always onramp when confirming an onramp quote.

string

Current status: awaiting_payment, processing, completed, failed, expired, refunded.

string

ID of the quote used for this ramp.

string

Blockchain network.

string

Crypto asset sent after fiat is received.

string

Fiat currency being paid.

string

Fiat amount paid by the user.

string

Crypto amount the wallet will receive after fees.

object

Fee breakdown from the quote: total, currency, processing_fee, network_fee.

string

Locked exchange rate.

string | null

On-chain transaction hash once crypto is sent.

string

Destination address for the crypto payout.

string

Your optional external reference.

object

Instructions for completing fiat payment. Varies by method.

string

ISO 8601 UTC timestamp when the transaction was created.

string

ISO 8601 UTC timestamp of the last update.

After creation, the transaction status is awaiting_payment. Crypto is sent to wallet_address once fiat is received. Track progress with GET /orders/{order_id}.

​Confirm an onramp quote

​Path parameters

​Request body

​Request

​Response

​Response fields

Confirm an onramp quote

Path parameters

Request body

Request

Response

Response fields