PurpleX Partner API Documentation

PurpleX Partner Payment API

Version 1.0 | REST | JSON

Authentication

Every API request must include your Bearer token in the Authorization header.

Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API token is generated from API Settings. Each token is bound to a specific IP + domain. Keep it secret.

Base URL

https://purplex.io/api/partner

POST

/merchant/validate

POST

/merchant/payment

GET

/payment/{partner_tx_id}

POST

/merchant/validate

Validate a merchant before showing payment confirmation to the user. Call this after user scans a QR.

Request Body

{
    "merchant_transaction_data": "test@paytm",
    "merchant_transaction_type": "upi"
}

Field	Type	Required	Description
`merchant_transaction_data`	string	Yes	UPI ID, account number, or PurpleX merchant code
`merchant_transaction_type`	string	Yes	`upi` \| `IMPS` \| `NEFT` \| `purplex`

Success Response 200

{
    "status": true,
    "merchant": {
        "name": null,
        "merchant_id": "test@paytm",
        "merchant_transaction_type": "upi"
    }
}

POST

/merchant/payment

Debit USDT from your pre-deposited wallet and send INR to the merchant's UPI/bank account.

Request Body

{
    "partner_tx_id":               "PARA_TX_001",
    "merchant_transaction_data":  "test@paytm",
    "merchant_transaction_type":  "upi",
    "crypto_symbol":              "USDT",
    "network":                    "TRC20",
    "crypto_amount":              8.5,
    "user_id":                    "USER_123",
    "user_name":                  "Rahul Shah",
    "user_email":                 "rahul@example.com"
}

Field	Type	Required	Description
`partner_tx_id`	string	Yes	Your unique TX ID — prevents duplicates
`merchant_transaction_data`	string	Yes	UPI ID / account / PurpleX code
`merchant_transaction_type`	string	Yes	`upi` \| `IMPS` \| `NEFT` \| `purplex`
`crypto_symbol`	string	Yes	`USDT`
`network`	string	Yes	`TRC20`
`crypto_amount`	number	Yes	Amount in USDT
`user_id`	string	Yes	Your user's ID
`user_name`	string	No	Your user's name
`user_email`	string	No	Your user's email

Success Response 201

{
    "status":         true,
    "message":        "Payment processed successfully.",
    "purplex_tx_id": "PXKM4KG4HPHIWP",
    "partner_tx_id": "PARA_TX_001",
    "crypto_amount": 8.5,
    "crypto_symbol": "USDT",
    "inr_amount":    853.14,
    "paid_at":       "2026-06-05T10:30:00Z"
}

Error Responses

422 Insufficient balance
422 UPI payout failed
409 Duplicate partner_tx_id
503 Rate temporarily unavailable

GET

/payment/{partner_tx_id}

Check the status of a previously processed payment.

{
    "status":                      true,
    "purplex_tx_id":              "PXKM4KG4HPHIWP",
    "partner_tx_id":              "PARA_TX_001",
    "merchant_transaction_type":  "upi",
    "paid_to":                    "test@paytm",
    "crypto_amount":              8.5,
    "payment_status":             "SUCCESS",
    "paid_at":                    "2026-06-05T10:30:00Z"
}

Webhook Callback

After every successful payment, PurpleX sends a POST to your configured Callback URL.

Set your callback URL in API Settings → Callback URL

Payload

{
    "event":                      "payment.success",
    "purplex_tx_id":              "PXKM4KG4HPHIWP",
    "partner_tx_id":              "PARA_TX_001",
    "merchant_transaction_type":  "upi",
    "paid_to":                    "test@paytm",
    "crypto_amount":              8.5,
    "status":                     "SUCCESS",
    "user_id":                    "USER_123",
    "paid_at":                    "2026-06-05T10:30:00Z",
    "signature":                  "a22efce2d2a927b8b97caafe9ca7e7..."
}

Retries: up to 3 times with 60s gap if your endpoint returns non-2xx.

Error Codes

HTTP Status	Meaning
201	Payment created successfully
200	Request successful
401	Invalid or missing API token
404	Resource not found
409	Duplicate partner_tx_id
422	Validation error or business logic failure
429	Rate limit exceeded
503	External service temporarily unavailable