Buy exam / result checker PIN

Bearer ds_live_ / ds_test_

POST/api/v1/merchant/education/purchase

Buys one or more exam PINs (WAEC, NECO, NABTEB and more). PINs and serial numbers are returned once the purchase is successful.

Language

curl -X POST "https://finaldatasub.com/api/v1/merchant/education/purchase" \
  -H "Authorization: Bearer ds_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "ORDER-10025",
    "biller": "waec",
    "product_id": 901,
    "quantity": 2,
    "phone": "08031234567"
  }'

Authentication

Send your secret API key in the header. Authorization: Token … and X-API-Key: … are also accepted.

Header	Value	Required
Authorization	Bearer ds_live_YOUR_KEY	Yes
Content-Type	application/json	Yes
Accept	application/json	Recommended

Authentication failures (401 UNAUTHORIZED, 403 IP_NOT_ALLOWED / ACCOUNT_SUSPENDED / API_ACCESS_NOT_APPROVED, 429 RATE_LIMITED) are listed in Authentication.

Parameters

Body parameters

Name	Type	Required	Description
reference	string	Yes	Your unique order reference and idempotency key (max 128 chars). Re-sending it returns the original transaction and never charges twice.
biller	string	Yes	Exam body slug, e.g. `waec`, `neco`, `nabteb` (List billers with `category=education` or `exam`).
product_id	integer \| string	Yes	PIN product id from Biller products (or its `code`).
quantity	integer	No	Number of PINs, 1–10 (default 1).
phone	string	No	Nigerian number, e.g. `08031234567`, `2348031234567` or `+2348031234567` (must match `/^(\+?234\|0)?[789][01]\d{8}$/`). Stored as `0XXXXXXXXXX`.
profile_id	string	No	Candidate profile id, for exam bodies that need one (max 40).
narration	string	No	Note stored on the transaction (max 255 chars).
save_beneficiary	boolean	No	Save the customer to your beneficiaries after a successful purchase (default `true`).
beneficiary_label	string	No	Label for the saved beneficiary (max 60 chars).

Responses

201 Created — Successful · 202 Accepted — Pending · 422 Unprocessable Entity — Failed (refunded)

{
  "status": "successful",
  "reference": "ORDER-10025",
  "channel": "api",
  "transaction_id": "DS261005103210X1Y2Z3A4",
  "category": "education",
  "message": "Transaction successful.",
  "biller": "WAEC",
  "biller_slug": "waec",
  "product_id": 901,
  "product": "WAEC Result Checker PIN",
  "phone": "08031234567",
  "customer_ref": "08031234567",
  "quantity": 2,
  "unit_amount": "3900.00",
  "amount": "7800.00",
  "face_amount": "7800.00",
  "fee": "0.00",
  "discount": "0.00",
  "total_deducted": "7800.00",
  "balance_before": "11135.00",
  "balance_after": "3335.00",
  "provider_reference": "PRV-88214610",
  "purchased_at": "2026-10-05T10:32:10+01:00",
  "pin_order_id": 311,
  "pins": [
    "123456789012",
    "210987654321"
  ],
  "serial_numbers": [
    "WRN0001234",
    "WRN0001235"
  ],
  "cards": [
    {
      "pin": "123456789012",
      "serial": "WRN0001234"
    },
    {
      "pin": "210987654321",
      "serial": "WRN0001235"
    }
  ]
}

Errors

Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.

Code	HTTP	When
INVALID_QUANTITY	400	Quantity must be between 1 and 10.
INSUFFICIENT_STOCK	400	Not enough PINs in stock. Nothing is charged.
INVALID_PHONE	400	`phone` is not a valid Nigerian number.
BILLER_NOT_FOUND	404	Unknown or inactive biller / network.
PRODUCT_NOT_FOUND	404	Plan id / code not found, inactive or not part of this biller.
SERVICE_UNAVAILABLE	503	The service or biller is disabled or temporarily unavailable.
INVALID_AMOUNT	400	Amount is zero or outside the biller's minimum / maximum.
DAILY_LIMIT_EXCEEDED	429	Your daily spend limit for this service is reached.
TIER_MAX_BALANCE / TIER_DAILY_LIMIT / TIER_MONTHLY_LIMIT	429	An account tier limit is reached. Upgrade KYC to raise it.
INSUFFICIENT_BALANCE	402	Wallet balance is too low for this purchase.
WALLET_INACTIVE	403	Your wallet is frozen or not active.
WALLET_BUSY	409	Another request is updating your wallet. Retry with the same reference.
TRANSACTION_FAILED	422	The provider could not deliver. Your wallet was refunded.
DUPLICATE	200 / 202 / 409	The reference was already used. The original transaction is returned.

curl -X POST "https://finaldatasub.com/api/v1/merchant/education/purchase" \ -H "Authorization: Bearer ds_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "reference": "ORDER-10025", "biller": "waec", "product_id": 901, "quantity": 2, "phone": "08031234567" }'

Header

Value

Required

Authorization

Bearer ds_live_YOUR_KEY

Yes

Content-Type

application/json

Yes

application/json

Recommended

Name

Type

Required

Description

reference

string

Yes

Your unique order reference and idempotency key (max 128 chars). Re-sending it returns the original transaction and never charges twice.

biller

string

Yes

Exam body slug, e.g. waec, neco, nabteb (List billers with category=education or exam).

product_id

integer | string

Yes

PIN product id from Biller products (or its code).

quantity

integer

Number of PINs, 1–10 (default 1).

phone

string

Nigerian number, e.g. 08031234567, 2348031234567 or +2348031234567 (must match /^(\+?234|0)?[789][01]\d{8}$/). Stored as 0XXXXXXXXXX.

profile_id

string

Candidate profile id, for exam bodies that need one (max 40).

narration

string

Note stored on the transaction (max 255 chars).

save_beneficiary

boolean

Save the customer to your beneficiaries after a successful purchase (default true).

beneficiary_label

string

Label for the saved beneficiary (max 60 chars).

{ "status": "successful", "reference": "ORDER-10025", "channel": "api", "transaction_id": "DS261005103210X1Y2Z3A4", "category": "education", "message": "Transaction successful.", "biller": "WAEC", "biller_slug": "waec", "product_id": 901, "product": "WAEC Result Checker PIN", "phone": "08031234567", "customer_ref": "08031234567", "quantity": 2, "unit_amount": "3900.00", "amount": "7800.00", "face_amount": "7800.00", "fee": "0.00", "discount": "0.00", "total_deducted": "7800.00", "balance_before": "11135.00", "balance_after": "3335.00", "provider_reference": "PRV-88214610", "purchased_at": "2026-10-05T10:32:10+01:00", "pin_order_id": 311, "pins": [ "123456789012", "210987654321" ], "serial_numbers": [ "WRN0001234", "WRN0001235" ], "cards": [ { "pin": "123456789012", "serial": "WRN0001234" }, { "pin": "210987654321", "serial": "WRN0001235" } ] }

Code

HTTP

When

INVALID_QUANTITY

400

Quantity must be between 1 and 10.

INSUFFICIENT_STOCK

400

Not enough PINs in stock. Nothing is charged.

INVALID_PHONE

400

phone is not a valid Nigerian number.

BILLER_NOT_FOUND

404

Unknown or inactive biller / network.

PRODUCT_NOT_FOUND

404

Plan id / code not found, inactive or not part of this biller.

SERVICE_UNAVAILABLE

503

The service or biller is disabled or temporarily unavailable.

INVALID_AMOUNT

400

Amount is zero or outside the biller's minimum / maximum.

DAILY_LIMIT_EXCEEDED

429

Your daily spend limit for this service is reached.

TIER_MAX_BALANCE / TIER_DAILY_LIMIT / TIER_MONTHLY_LIMIT

429

An account tier limit is reached. Upgrade KYC to raise it.

INSUFFICIENT_BALANCE

402

Wallet balance is too low for this purchase.

WALLET_INACTIVE

403

Your wallet is frozen or not active.

WALLET_BUSY

409

Another request is updating your wallet. Retry with the same reference.

TRANSACTION_FAILED

422

The provider could not deliver. Your wallet was refunded.

DUPLICATE

200 / 202 / 409

The reference was already used. The original transaction is returned.

API Documentation

Buy exam / result checker PIN

Authentication

Parameters

Body parameters

Responses

Errors

API Documentation

Buy exam / result checker PIN

Authentication

Parameters

Body parameters

Responses

Errors