Create a quote

POST /v1/services/quote : lock the customer price, fee, and FX for a service purchase.

POST /v1/services/quote

Prices a service purchase before the customer commits. The quote locks the destination amount, the OuiPay fee, and (for cross-currency orders) the FX rate, and returns a quote_id to bind on order creation.

Quotes are optional for same-currency orders but required after any FX: an order whose service country currency differs from the customer's paying currency must carry a live quote_id.

Headers

Header	Required	Value
`Authorization`	yes	`Bearer sk_...`
`Content-Type`	yes	`application/json`

Body

Field	Type	Required	Notes
`provider_cost_minor`	int	yes	Destination service value, minor units
`currency`	string	yes	Currency of `provider_cost_minor` (ISO 4217)
`country_code`	string	yes	Service country
`service_code`	string	yes	Catalogue code
`payment_method`	string	no	Intended method: fees can differ per method
`phone`	string	no	Recipient phone when it affects pricing
`account_ref`	string	no	Recipient account when it affects pricing

For fixed-price plans, provider_cost_minor is the plan's amount_minor. For open-amount services it is the amount the customer entered.

Request

curl https://api.ouipay.africa/v1/services/quote \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider_cost_minor": 500000,
    "currency": "NGN",
    "country_code": "NG",
    "service_code": "electricity",
    "payment_method": "wallet"
  }'

Response `200`

{
  "data": {
    "quote_id": "01M2S17...",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "destination_amount_minor": 500000,
    "converted_amount_minor": 500000,
    "fee_minor": 10000,
    "customer_amount_minor": 510000,
    "currency": "NGN",
    "provider_cost_minor": 500000,
    "fx_rate": null,
    "cross_currency": false,
    "promotion_discount_minor": 0,
    "promotion_code": null,
    "expires_at": "2026-09-18T02:05:00Z"
  }
}

Field	Type	Notes
`quote_id`	string	Bind on `POST /services/orders`
`customer_amount_minor`	int	What the customer pays: `converted_amount_minor + fee_minor`
`converted_amount_minor`	int	Destination value converted into `source_currency`
`destination_amount_minor`	int	The service value delivered, in `destination_currency`
`fx_rate`	string	Locked customer rate when `cross_currency` is true
`cross_currency`	boolean	Customer pays a different currency than the destination
`expires_at`	string	Orders against an expired quote are rejected

Show customer_amount_minor, fee_minor, and (when cross-currency) fx_rate on the review screen. These are the locked terms: the order cannot reprice.

Errors

HTTP	`error.code`	Cause
400	`VALIDATION`	Missing or malformed field
403	`SERVICE_COUNTRY_NOT_ELIGIBLE`	Country not eligible for this account
422	`SERVICE_UNAVAILABLE`	Service not offered in the requested country