Validate a recipient

POST /v1/services/{serviceCode}/validate : verify a meter, smartcard, or account before quoting.

POST /v1/services/{serviceCode}/validate

Verifies the recipient identifier against the fulfilment rail before money moves: meter number for electricity/water, smartcard for tv, customer ID for internet, candidate ID for education. Call it whenever the definition marks a step requires_validation, and pass the response back as validation_snapshot on the order.

Headers

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

Body

Field	Type	Required	Notes
`country_code`	string	yes	Service country
`account_ref`	string	yes	The recipient identifier being verified
`operator_code`	string	no	Selected operator (required by most rails)
`product_code`	string	no	Selected plan, when the rail needs it
`meter_type`	string	no	Selected variant (e.g. `prepaid`)
`phone`	string	no	Contact phone when the rail asks for it

Request

curl https://api.ouipay.africa/v1/services/electricity/validate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "NG",
    "account_ref": "04591234567",
    "operator_code": "ikeja-electric",
    "meter_type": "prepaid"
  }'

Response `200`

{
  "data": {
    "service_code": "electricity",
    "country_code": "NG",
    "account_ref": "04591234567",
    "valid": true,
    "customer_name": "A. OKONKWO",
    "address": "12 ADEOLA ST, IKEJA",
    "serviceability": { "serviceable": true, "reason": null }
  }
}

Field	Type	Notes
`valid`	boolean	The identifier resolved on the rail
`customer_name`	string	Registered name when the rail returns one
`serviceability`	object	`serviceable`: a rail can actually fulfil this recipient
`phone_validation`	object	`airtime`/`data` only: normalized number, type, carrier

valid and serviceability.serviceable are different checks: a structurally valid meter number can still be unserviceable in a country with no fulfilment binding. Require both before quoting.

For airtime and data, phone_validation carries the platform-level result (valid, normalized E.164, country_code, number_type, carrier, messages) ahead of the rail check: impossible numbers and country/number mismatches fail here without reaching the rail. When normalized is present, the rail check already ran against it: reuse that value on the order.

Errors

HTTP	`error.code`	Cause
422	`VALIDATION_ERROR`	Missing `account_ref`/`country_code`, or the rail rejected the lookup
403	`SERVICE_COUNTRY_NOT_ELIGIBLE`	Country not eligible for this account
422	`SERVICE_UNAVAILABLE`	Service not offered in the requested country