GEThttps://onepayment.com.ng/api/network/

Get all network IDs. Use the returned `id` as `network` in purchase requests.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/network/" -H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

[
  {"id": 1, "name": "MTN"},
  {"id": 2, "name": "GLO"},
  {"id": 3, "name": "9MOBILE"},
  {"id": 4, "name": "AIRTEL"}
]

GEThttps://onepayment.com.ng/api/data_plans/

Get all available data plans grouped by network. Use `id` as `plan` in purchase requests.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/data_plans/" -H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "MTN_PLAN": [
    {
      "id": 12,
      "network": 1,
      "plan_type": "SME",
      "month_validate": "30 Days",
      "plan": "1.5GB",
      "plan_amount": "490"
    }
  ],
  "GLO_PLAN": [],
  "9MOBILE_PLAN": [],
  "AIRTEL_PLAN": []
}

POSThttps://onepayment.com.ng/api/data/

Purchase data bundle. Routes automatically

cURL EXAMPLE

curl -X POST "https://onepayment.com.ng/api/data/" \
-H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network": 1, "plan": 12, "mobile_number": "08031234567", "Ported_number": false}'

PAYLOAD

Field	Type	Required	Description
network	integer	Yes	Network ID from /api/network/
plan	integer	Yes	Plan ID from /api/data_plans/
mobile_number	string	Yes	11 digits
Ported_number	boolean	No	Default: false

RESPONSE SUCCESS 201

{
  "id": 102,
  "ident": "24082714310098765432def456",
  "mobile_number": "08031234567",
  "Status": "successful",
  "plan_name": "1.5GB",
  "plan_network": "MTN",
  "purchase_amount": "500",
  "plan_amount": "490",
  "balance_before": "4500",
  "balance_after": "4010",
  "create_date": "2026-08-27T14:31:00Z"
}

RESPONSE ERROR 400

{
  "error": "You can't purchase this plan due to insufficient balance ₦400.00 Kindly Fund your Wallet"
}

GEThttps://onepayment.com.ng/api/data/

List all your data transactions. Supports search and pagination.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/data/?search=08031234567" -H "Authorization: Token YOUR_TOKEN"

QUERY PARAMS

Param	Type	Description
search	string	Search by id, ident, or mobile_number
page	integer	Page number

RESPONSE 200

{
  "count": 25,
  "next": "https://onepayment.com.ng/api/data/?page=2",
  "previous": null,
  "results": [
    {
      "id": 101,
      "ident": "24082714302212345678abc123",
      "mobile_number": "08031234567",
      "Status": "successful",
      "plan_name": "1.5GB",
      "plan_amount": "490"
    }
  ]
}

GEThttps://onepayment.com.ng/api/data/{id}

Get details of a single data transaction. No trailing slash.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/data/102" -H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "id": 101,
  "ident": "24082714302212345678abc123",
  "user": 12,
  "network": 1,
  "plan": 12,
  "mobile_number": "08031234567",
  "Ported_number": false,
  "Status": "successful",
  "plan_name": "1.5GB",
  "plan_network": "MTN",
  "purchase_amount": "500",
  "plan_amount": "490",
  "balance_before": "4500",
  "balance_after": "4010",
  "create_date": "2026-08-27T14:31:00Z",
  "update_date": "2026-08-27T14:31:05Z"
}

RESPONSE ERROR 404

{"detail": "Not found."}

GETError Codes & Validation

Common error responses you may encounter when using the Data API

Code	Message	Description
400	invalid mobile number	Phone number format is invalid or doesn't match network
400	insufficient balance	Wallet balance is less than plan amount
400	Phone number has been Blacklist	Number is blacklisted and cannot receive data
400	Data not available on this network currently	Network vendor is temporarily down
400	GIFTING/SME/SOCIAL Data under maintainace	Plan type is currently under maintenance
400	Unverified User are limited to {limit} naira per day	Daily transaction limit exceeded for unverified account
404	invalid plan id for {network}	Plan ID does not exist for selected network

Refund Policy: If Status becomes failed, amount is automatically refunded to wallet with description DATA topup Refund for {number}

POSThttps://onepayment.com.ng/api/v1/airtime/

Purchase airtime instantly. Wallet debited immediately.

PAYLOAD

Field	Type	Required	Description
network	integer	Yes	1=MTN, 2=GLO, 3=9MOBILE, 4=AIRTEL
mobile_number	string	Yes	11 digits
amount	string	Yes	Minimum ₦100
airtime_type	string	Yes	VTU or Share and Sell
Ported_number	boolean	No	Default: false

cURL EXAMPLE

curl -X POST "https://onepayment.com.ng/api/v1/airtime/" \
-H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network": 1, "mobile_number": "08031234567", "amount": "500", "airtime_type": "VTU"}'

RESPONSE SUCCESS 201

{
  "id": 55,
  "ident": "24082814310012345678abc123",
  "Status": "successful",
  "paid_amount": "490.00",
  "balance_after": "4010.00"
}

GEThttps://onepayment.com.ng/api/v1/airtime/{id}/

Get single airtime transaction by ID

RESPONSE 200

{"id": 55, "Status": "successful", "mobile_number": "08031234567"}

NIN Verification API

Verify NIN by NIN, Phone, Tracking ID, or Demography Search. Wallet is debited on submission. If provider returns Not Found, amount is automatically refunded with provider error message. Returns full verified data + signed PDF valid for 30 days (signed link expires in 5 minutes).

Base URL: https://onepayment.com.ng
Authentication: Authorization: Token YOUR_API_TOKEN IsAuthenticated
Content-Type: application/json
Card Types: regular, premium
Verification Types: NIN Verification, NIN Phone Search, NIN Tracking, NIN Demography Search
Wallet: Ensure sufficient balance. 402 if insufficient. 400 with refund if Not Found.
PDF: 30 days from create_date. Use /generate-pdf/ to refresh 5-min signed link.

ENDPOINTS

Method	Endpoint	Description
POST	`/api/v1/nin-verification/`	Create verification
GET	`/api/v1/nin-verification/history/`	List history
GET	`/api/v1/nin-verification/{pk}/`	Get single
GET	`/api/v1/nin-verification/{pk}/generate-pdf/`	Generate signed PDF link
GET	`/api/v1/nin-verification/pdf/{signed_id}/`	Download PDF (signed)

POSThttps://onepayment.com.ng/api/v1/nin-verification/

Submit verification request. Wallet debited immediately. Refunded on provider Not Found.

Headers

Authorization: Token YOUR_API_TOKEN
Content-Type: application/json

1. NIN Verification

{
  "verification_type": "NIN Verification",
  "card_type": "regular",
  "nin": "12345678901",
  "Accept_Terms": true
}

Field	Type	Required	Note
verification_type	string	Yes	`NIN Verification`
card_type	string	Yes	`regular` / `premium`
nin	string	Yes	11 digits
Accept_Terms	bool	Yes	Must be true

2. NIN Phone Search

{
  "verification_type": "NIN Phone Search",
  "card_type": "regular",
  "phone": "08012345678",
  "Accept_Terms": true
}

3. NIN Tracking

{
  "verification_type": "NIN Tracking",
  "card_type": "regular",
  "tracking_id": "TRK123456",
  "Accept_Terms": true
}

4. NIN Demography Search

{
  "verification_type": "NIN Demography Search",
  "card_type": "premium",
  "firstname_search": "John",
  "lastname_search": "Doe",
  "gender_search": "MALE",
  "dob_search": "1990-01-01",
  "Accept_Terms": true
}

RESPONSE SUCCESS 200

{
  "success": true,
  "message": "NIN Verification successful",
  "verification_id": 456,
  "amount": 100.0,
  "pdf_expiry_days": 30,
  "data": {
    "verification_id": 456,
    "ident": "NIN20250825ABC123",
    "verification_type": "NIN Verification",
    "card_type": "regular",
    "nin": "12345678901",
    "phone": null,
    "tracking_id": null,
    "full_name": "JOHN MICHAEL DOE",
    "first_name": "JOHN",
    "last_name": "DOE",
    "phone_result": "08012345678",
    "gender": "MALE",
    "birthdate": "1990-01-01",
    "photo_url": "https://onepayment.com.ng/media/nin_photos/nin_12345678901.jpg",
    "card_image": "https://onepayment.com.ng/media/nin_cards/regular.png",
    "status": "successful",
    "amount": 100.0,
    "message": "NIN Verification successful",
    "report_id": "RPT12345",
    "create_date": "2026-08-25T10:00:00Z",
    "pdf_expired": false,
    "expires_at": "2026-09-24T10:00:00Z",
    "pdf_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9/",
    "pdf_download_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9/",
    "can_download_pdf": true
  },
  "result": { // same as data }
}

RESPONSE PROCESSING 200

{
  "success": true,
  "message": "Request submitted successfully. Awaiting admin review.",
  "verification_id": 456,
  "amount": 100.0,
  "status": "processing"
}

RESPONSE ERROR - NOT FOUND + REFUNDED 400

{
  "success": false,
  "error": "NIN not found for phone 09038749622"
}

Wallet is auto-refunded on this error.

RESPONSE ERROR - VALIDATION 400

{
  "success": false,
  "error": "Invalid form",
  "errors": {"nin": ["NIN must be exactly 11 digits."]}
}

RESPONSE ERROR - INSUFFICIENT BALANCE 402

{"success": false, "error": "Insufficient balance"}

GEThttps://onepayment.com.ng/api/v1/nin-verification/history/

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/nin-verification/history/" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "count": 1,
  "results": [
    {
      "verification_id": 456,
      "verification_type": "NIN Verification",
      "card_type": "regular",
      "status": "successful",
      "full_name": "JOHN DOE",
      "amount": 100.0,
      "pdf_expired": false,
      "expires_at": "2026-09-24T10:00:00Z",
      "pdf_download_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9/",
      "can_download_pdf": true,
      "create_date": "2026-08-25T10:00:00Z"
    }
  ]
}

GEThttps://onepayment.com.ng/api/v1/nin-verification/{pk}/

Get details of single verification. Same object as data in POST.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/nin-verification/456/" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "verification_id": 456,
  "verification_type": "NIN Verification",
  "card_type": "regular",
  "nin": "12345678901",
  "full_name": "JOHN DOE",
  "photo_url": "https://onepayment.com.ng/media/nin_photos/xxx.jpg",
  "card_image": "https://onepayment.com.ng/media/nin_cards/regular.png",
  "status": "successful",
  "pdf_download_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ...",
  "can_download_pdf": true
}

GEThttps://onepayment.com.ng/api/v1/nin-verification/{pk}/generate-pdf/

Generate new 5-minute signed link. Only if status=successful and within 30 days.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/nin-verification/456/generate-pdf/" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE SUCCESS 200

{
  "success": true,
  "message": "PDF ready",
  "pdf_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ...",
  "pdf_download_url": "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ...",
  "expires_at": "2026-08-25T15:35:00Z"
}

RESPONSE ERROR 403

{"success": false, "error": "PDF download expired. 30 days limit."}

GEThttps://onepayment.com.ng/api/v1/nin-verification/pdf/{signed_id}/

Download PDF file. Signed_id must be valid (5 min expiry).

cURL EXAMPLE

curl -L "https://onepayment.com.ng/api/v1/nin-verification/pdf/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9/" -o NIN.pdf

RESPONSE

Binary PDF Content-Type: application/pdf with filename NIN_{type}_{firstname}_{timestamp}.pdf

403 Link expired / Invalid link / PDF not available or expired if expired.

GET /api/v1/fundtransfer/banks/

Use this to load the bank dropdown, show user wallet balance, and check daily transfer limits before initiating a transfer.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/fundtransfer/banks/" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "status": true,
  "banks": [
    {
      "id": 1,
      "code": "000013",
      "name": "Guaranty Trust Bank",
      "short_name": "GTBANK",
      "logo_url": "https://cdn.onepayment.ng/banks/gtb.png",
      "is_active": true
    }
  ],
  "bank_count": 25,
  "wallet_balance": 20010.00,
  "daily_limit": 50000.00,
  "today_spent": 15000.00,
  "today_remaining": 35000.00
}

POST /api/v1/fundtransfer/sync-banks/

Admin only. Updates your bank list from OnePayment to ensure you always have the latest banks and codes.

RESPONSE 200

{
  "status": true,
  "message": "25 banks updated successfully",
  "banks": [],
  "bank_count": 25
}

POST /api/v1/fundtransfer/verify-account/

Verify a beneficiary account number and bank before sending money. Call this on blur of account number to show account name.

PAYLOAD

Field	Type	Required	Validation
bank_code	string	Yes	Bank code from /banks/
account_number	string	Yes	Exactly 10 digits

cURL EXAMPLE

curl -X POST "https://onepayment.com.ng/api/v1/fundtransfer/verify-account/" \
-H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"bank_code": "000013", "account_number": "0123456789"}'

RESPONSE SUCCESS 200

{
  "status": true,
  "account_name": "JOHN DOE"
}

RESPONSE ERROR 400

{"status": false, "message": "Account number must be 10 digits"}

POST /api/v1/fundtransfer/fee/

Preview the fee and total amount that will be debited. Also validates KYC limit and wallet balance before you send.

PAYLOAD

Field	Type	Required	Description
amount	number/string	Yes	Amount to send. Min ₦100.00

RESPONSE 200

{
  "status": true,
  "amount": "5000.00",
  "fee": "0.00",
  "total_debited": "5000.00",
  "wallet_balance": "20010.00",
  "daily_remaining": "35000.00",
  "message": "Fee calculated successfully"
}

POST /api/v1/fundtransfer/

Send money to a bank account. You must verify the account first. Wallet is only debited if the transfer is successful.

PAYLOAD

Field	Type	Required	Description
bank_id	integer	Yes	Use the `id` from /banks/ endpoint
account_number	string	Yes	10 digit account number
amount	number	Yes	Min ₦100.00
narration	string	No	Max 255. Defaults to your Full Name

cURL EXAMPLE

curl -X POST "https://onepayment.com.ng/api/v1/fundtransfer/" \
-H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"bank_id": 1, "account_number": "0123456789", "amount": 5000.00, "narration": "Invoice Payment"}'

RESPONSE SUCCESS 201

{
  "status": true,
  "message": "₦5000.00 sent to JOHN DOE successfully. Fee: ₦0.00",
  "transfer": {
    "id": 801,
    "reference": "OP7A8B9C0D1E2",
    "ident": "OP7A8B9C0D1E2",
    "bank": {"id": 1, "code": "000013", "name": "Guaranty Trust Bank", "short_name": "GTB", "logo_url": "...", "is_active": true},
    "bank_name": "Guaranty Trust Bank",
    "bank_code": "000013",
    "account_number": "0123456789",
    "account_name": "JOHN DOE",
    "amount": "5000.00",
    "charge": "0.00",
    "total_debited": "5000.00",
    "narration": "Invoice Payment",
    "Status": "successful",
    "failure_reason": null,
    "session_id": "SESS123",
    "provider_reference": "OPX123456",
    "create_date": "2026-08-27T14:31:00Z",
    "completed_at": "2026-08-27T14:31:05Z"
  }
}

GET /api/v1/fundtransfer/status/<str:reference>/

Check the current status of a specific transfer. This endpoint also auto-updates the status with OnePayment if it was pending.

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/fundtransfer/status/OP7A8B9C0D1E2/" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "status": true,
  "transfer": {... Full transfer object }
}

GET /api/v1/fundtransfer/history/

Get your transfer history. This endpoint automatically checks and updates the status of your first 5 pending transfers.

QUERY PARAMS

Param	Type	Description
status	string	Filter: `all`, `successful`, `pending`, `failed`, `reversed`

cURL EXAMPLE

curl -X GET "https://onepayment.com.ng/api/v1/fundtransfer/history/?status=pending" \
-H "Authorization: Token YOUR_TOKEN"

RESPONSE 200

{
  "status": true,
  "transfers": [... array of transfer objects ]
}

GETStatus & Auto Refund Policy

Status	Meaning	Wallet Action
`pending`	Sent to OnePayment. Awaiting bank confirmation	Not debited
`successful`	Credited to beneficiary	Debited immediately
`failed`	Rejected by destination bank	Not debited
`reversed`	Failed and auto-refunded	Refunded `total_debited`
`deleted`	Soft deleted	N/A

Auto Refund: When a transfer fails, OnePayment automatically reverses it and refunds the total_debited amount to your wallet. A wallet log is created: Fund Transfer Refund ({bank_name}) - {account_number}

Auto-Reconciliation: Only the `/status/` and `/history/` endpoints check OnePayment for updates. The `/banks/` endpoint does not.

Data Purchase API

Airtime Purchase API

NIN Verification API

OnePayment Funds Transfer API