Buy recharge PINs

Bearer ds_live_ / ds_test_

POST/api/v1/merchant/recharge-pin/purchase

Buys printable recharge card PINs from stock. PINs, serials and load codes are returned immediately on success.

Language

curl -X POST "https://finaldatasub.com/api/v1/merchant/recharge-pin/purchase" \
  -H "Authorization: Bearer ds_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "PIN-20261005-01",
    "network": "MTN",
    "denomination": 100,
    "quantity": 2,
    "name_on_card": "Ada Stores"
  }'

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.
network	string	One of	`MTN`, `GLO`, `AIRTEL` or `9MOBILE`.
network_id	integer	One of	MSORG network id: 1 = MTN, 2 = GLO, 3 = 9MOBILE, 4 = AIRTEL.
biller	string	One of	Recharge PIN biller slug or id from Recharge PIN networks. Takes priority over the others.
denomination	number	Yes	Face value per PIN, from Recharge PIN denominations.
quantity	integer	Yes	Number of PINs, 1–39.
name_on_card	string	No	Business name to print on the cards (max 60 chars).
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": "PIN-20261005-01",
  "channel": "api",
  "transaction_id": "DS261005104500T1U2V3W4",
  "category": "rechargepin",
  "message": "Transaction successful.",
  "network": "MTN",
  "biller": "MTN Recharge PIN",
  "biller_slug": "mtn-recharge-pin",
  "quantity": 2,
  "unit_amount": "98.00",
  "amount": "196.00",
  "face_amount": "200.00",
  "fee": "0.00",
  "discount": "4.00",
  "total_deducted": "196.00",
  "balance_before": "3531.00",
  "balance_after": "3335.00",
  "purchased_at": "2026-10-05T10:45:00+01:00",
  "pin_order_id": 512,
  "name_on_card": "Ada Stores",
  "denomination": "100.00",
  "total_amount": "196.00",
  "pins": [
    {
      "pin": "1234567890123456",
      "serial": "SN00012345",
      "load_code": "*311*PIN#"
    },
    {
      "pin": "6543210987654321",
      "serial": "SN00012346",
      "load_code": "*311*PIN#"
    }
  ]
}

Errors

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

Code	HTTP	When
REQUIRED	400	None of `biller`, `network` or `network_id` was sent.
INVALID_QUANTITY	400	Quantity must be between 1 and 39.
INSUFFICIENT_STOCK	400	Not enough PINs for this denomination. Nothing is charged.
BILLER_NOT_FOUND	404	Unknown or inactive biller / network.
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/recharge-pin/purchase" \ -H "Authorization: Bearer ds_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "reference": "PIN-20261005-01", "network": "MTN", "denomination": 100, "quantity": 2, "name_on_card": "Ada Stores" }'

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.

network

string

One of

MTN, GLO, AIRTEL or 9MOBILE.

network_id

integer

One of

MSORG network id: 1 = MTN, 2 = GLO, 3 = 9MOBILE, 4 = AIRTEL.

biller

string

One of

Recharge PIN biller slug or id from Recharge PIN networks. Takes priority over the others.

denomination

number

Yes

Face value per PIN, from Recharge PIN denominations.

quantity

integer

Yes

Number of PINs, 1–39.

name_on_card

string

Business name to print on the cards (max 60 chars).

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": "PIN-20261005-01", "channel": "api", "transaction_id": "DS261005104500T1U2V3W4", "category": "rechargepin", "message": "Transaction successful.", "network": "MTN", "biller": "MTN Recharge PIN", "biller_slug": "mtn-recharge-pin", "quantity": 2, "unit_amount": "98.00", "amount": "196.00", "face_amount": "200.00", "fee": "0.00", "discount": "4.00", "total_deducted": "196.00", "balance_before": "3531.00", "balance_after": "3335.00", "purchased_at": "2026-10-05T10:45:00+01:00", "pin_order_id": 512, "name_on_card": "Ada Stores", "denomination": "100.00", "total_amount": "196.00", "pins": [ { "pin": "1234567890123456", "serial": "SN00012345", "load_code": "*311*PIN#" }, { "pin": "6543210987654321", "serial": "SN00012346", "load_code": "*311*PIN#" } ] }

Code

HTTP

When

REQUIRED

400

None of biller, network or network_id was sent.

INVALID_QUANTITY

400

Quantity must be between 1 and 39.

INSUFFICIENT_STOCK

400

Not enough PINs for this denomination. Nothing is charged.

BILLER_NOT_FOUND

404

Unknown or inactive biller / network.

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 recharge PINs

Authentication

Parameters

Body parameters

Responses

Errors

API Documentation

Buy recharge PINs

Authentication

Parameters

Body parameters

Responses

Errors