Create and confirm quotes with locked rates and fees

Every PeerPesa ramp runs in two calls: create a quote to lock the exchange rate and fee breakdown, then confirm the quote to start the onramp or offramp. A quote stays valid for exactly 30 minutes, so show the user the rate, fees, and final amount, and confirm only after they accept.

Create a quote

POST /quotes returns the locked rate, fee breakdown, amounts, and expires_at (30 minutes after creation).

Show the quote to your user

Display rate, fee.total, and destination_amount, plus a countdown to expires_at.

Confirm the quote

POST /quotes/{id}/confirm with the wallet address (onramp) or beneficiary (offramp). PeerPesa creates the transaction and returns it.

Quotes expire after 30 minutes. Confirming an expired quote returns 422 quote_expired, and confirming a quote twice returns 409 quote_already_used. Create a new quote in either case.

Create a quote

POST /quotes Locks a rate and fee breakdown for a specific network, asset, fiat currency, amount, and method.

Request body

string

required

Ramp type: onramp (fiat to crypto) or offramp (crypto to fiat).

string

required

Blockchain network: stellar or celo.

string

required

Asset code on the network. Stellar: XLM, USDC. Celo: CELO, USDT, USDC, CUSD.

string

required

Fiat currency code: KES, TZS, NGN, ZAR, ZMW.

string

required

Amount as a decimal string, for example "100.00".

string

required

Currency the amount refers to: the asset code or the fiat_currency code.

string

required

Payin or payout method: mobile_money or bank_transfer. Availability varies by country.

Request

curl -X POST https://api.peerpesa.co/v1/quotes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "onramp",
    "network": "stellar",
    "asset": "USDC",
    "fiat_currency": "KES",
    "amount": "10000.00",
    "amount_currency": "KES",
    "method": "mobile_money"
  }'

const res = await fetch("https://api.peerpesa.co/v1/quotes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "onramp",
    network: "stellar",
    asset: "USDC",
    fiat_currency: "KES",
    amount: "10000.00",
    amount_currency: "KES",
    method: "mobile_money",
  }),
});
const quote = await res.json();

Response

{
  "id": "qt_8f2k3m9n1p0q",
  "type": "onramp",
  "network": "stellar",
  "asset": "USDC",
  "fiat_currency": "KES",
  "method": "mobile_money",
  "rate": "129.45",
  "source_amount": "10000.00",
  "source_currency": "KES",
  "fee": {
    "total": "1.50",
    "currency": "USDC",
    "processing_fee": "1.00",
    "network_fee": "0.50"
  },
  "destination_amount": "75.75",
  "destination_currency": "USDC",
  "status": "active",
  "created_at": "2026-10-15T10:00:00Z",
  "expires_at": "2026-10-15T10:30:00Z"
}

Response fields

string

Unique quote identifier, for example qt_8f2k.... Use it to confirm the quote.

string

onramp or offramp.

string

Locked exchange rate as a decimal string.

string

Amount on the source side before fees, in source_currency.

object

Fee charged for processing this quote.

Show properties

string

Total fee deducted.

string

Currency the fee is charged in.

string

PeerPesa processing fee.

string

Blockchain network fee.

string

Final amount the recipient receives after fees, in destination_currency.

string

active, confirmed, or expired.

string

ISO 8601 UTC timestamp when the quote expires, 30 minutes after created_at.

Confirm a quote

POST /quotes/{id}/confirm Accepts an active quote and creates the ramp transaction at the locked rate and fee. The body depends on the quote type.

Path parameters

string

required

ID of an active quote, for example qt_8f2k3m9n1p0q.

Request body

Onramp
Offramp

string

required

Address on the quote’s network that receives the crypto.

string

Stellar memo to attach to the payout, if the receiving wallet needs one.

object

required

Who pays the fiat. For mobile_money, include phone_number. For bank_transfer, include account_name.

string

Your own identifier, returned on the transaction.

Request

curl -X POST https://api.peerpesa.co/v1/quotes/qt_8f2k3m9n1p0q/confirm \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1f0a2e-order-12345" \
  -d '{
    "wallet_address": "GABC...XYZ",
    "payer": { "phone_number": "+254712345678" },
    "reference": "order-12345"
  }'

const res = await fetch(
  `https://api.peerpesa.co/v1/quotes/${quote.id}/confirm`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "6c1f0a2e-order-12345",
    },
    body: JSON.stringify({
      wallet_address: "GABC...XYZ",
      payer: { phone_number: "+254712345678" },
      reference: "order-12345",
    }),
  }
);
const transaction = await res.json();

Response

Returns the transaction created from the quote. Onramps start in awaiting_payment with payment_instructions. Offramps start in awaiting_deposit with a deposit object. See Onramp and Offramp for the full transaction fields.

{
  "id": "txn_9a3b4c5d6e7f",
  "type": "onramp",
  "status": "awaiting_payment",
  "quote_id": "qt_8f2k3m9n1p0q",
  "network": "stellar",
  "asset": "USDC",
  "fiat_currency": "KES",
  "rate": "129.45",
  "source_amount": "10000.00",
  "destination_amount": "75.75",
  "fee": {
    "total": "1.50",
    "currency": "USDC",
    "processing_fee": "1.00",
    "network_fee": "0.50"
  },
  "wallet_address": "GABC...XYZ",
  "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": "2026-10-15T10:05:00Z",
  "updated_at": "2026-10-15T10:05:00Z"
}

Retrieve a quote

GET /quotes/{id} Returns a quote with its current status and expires_at. The response has the same shape as the create response.

curl https://api.peerpesa.co/v1/quotes/qt_8f2k3m9n1p0q \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch("https://api.peerpesa.co/v1/quotes/qt_8f2k3m9n1p0q", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const quote = await res.json();

Quote statuses

Status	Meaning
`active`	Valid and can be confirmed.
`confirmed`	Confirmed; a transaction was created from it.
`expired`	Older than 30 minutes and can no longer be confirmed.

Errors

Code	Status	Cause
`quote_expired`	422	The quote is older than 30 minutes.
`quote_already_used`	409	The quote was already confirmed.
`quote_not_found`	404	No quote with this ID exists for your account.
`beneficiary_mismatch`	422	The beneficiary currency or method does not match the quote.
`invalid_wallet_address`	422	The address is not valid for the quote’s network.

See Error Codes for the full list.

​Create a quote

​Request body

​Request

​Response

​Response fields

​Confirm a quote

​Path parameters

​Request body

​Request

​Response

​Retrieve a quote

​Quote statuses

​Errors

Create a quote

Request body

Request

Response

Response fields

Confirm a quote

Path parameters

Request body

Request

Response

Retrieve a quote

Quote statuses

Errors