Distributor Card API

Create cardholders & issue virtual cards

A simple REST API to onboard cardholders (with KYC) and issue virtual cards programmatically.

Base URL

https://uat-cards.netpay247.com/api/v1

Authentication

Send both headers on every request.

X-Api-Key: dk_live_xxxxxxxx
X-Access-Key: <your-access-key>

Flow

Create cardholder

POST /cardholders → get a holderId.

Wait for ACTIVE

Poll GET /cardholders/:id/status until status is ACTIVE.

Issue the card

POST /cards to issue the virtual card.

💡 Send an Idempotency-Key header on POST /cards to make retries safe.

Endpoints

POST/api/v1/cardholders

Create the end user + cardholder. Body is multipart/form-data so KYC documents upload directly.

Field	Type	Required	Notes
email	Text	Yes	Unique per user
firstName	Text	Yes	—
lastName	Text	Yes	—
country	Text	Yes	ISO-2 code, e.g. IN
mobile	Text	Yes	Digits only
kycDocType	Text	Yes	passport / id_card / drivers_license
kycIdNumber	Text	Yes	Document number
docFront	File	Yes	ID front image
docBack	File	No	ID back image
selfie	File	No	Selfie / portrait
kycDob / kycIssueDate / kycExpiryDate	Text	No	YYYY-MM-DD
gender / areaCode / town	Text	No	Optional details

NetPay API · /cardholders

201 Created

{
  "success": true,
  "userId": "6a2a5427d6bd69d062555175",
  "holderId": "183633",
  "holderStatus": "IN_REVIEW"
}

GET/api/v1/cardholders/:holderId/status

Poll the verification status. Issue a card only once it is ACTIVE.

NetPay API · /cardholders/:id/status

200 OK

{
  "success": true,
  "holderId": "183633",
  "status": "ACTIVE",          // IN_REVIEW | ACTIVE | REJECTED
  "canIssueCard": true
}

POST/api/v1/cards

Issue a VIRTUAL card against an ACTIVE holder. loadAmount is debited from your prepaid wallet.

Request body (JSON)

{
  "holderId": "183633",
  "cardType": "virtual",
  "card_product_id": "111031",
  "currency": "USD",
  "loadAmount": 20
}

NetPay API · /cards

201 Created

{
  "success": true,
  "cardId": "6a2b...",
  "uqpayCardId": "98765",
  "holderId": "183633",
  "status": "pending",
  "loadAmount": 20,
  "loadedBalance": 20
}

GET/api/v1/cards/:cardId/reveal

Reveal full card details (number, CVV, expiry). :cardId is the uqpayCardId returned when the card was created.

NetPay API · /cards/:id/reveal

200 OK

{
  "success": true,
  "cardDetails": {
    "card_id": "98765",
    "card_number": "4111111111111234",
    "cvv": "123",
    "expiry_date": "12/28"
  }
}

Errors

401

Invalid API credentials

402

Insufficient wallet balance

404

Card / cardholder not found

409

Cardholder still under verification

422

Validation error or cardholder rejected