FinixPay API Documentation

Authentication

All requests are authenticated using the token provided by Finixpay. Include it as a JSON field in the request body.

Note: Callback URLs must be pre‑registered, and the originating IP must be whitelisted for payout callbacks.

💰 Pay‑In API

Initiate

Method	POST
Endpoint	`https://api.finixpays.com/api/pg/phonepe/initiate`

{
  "token": "YOUR_TOKEN",
  "userid": "MID",
  "amount": "10",
  "mobile": "9999999999",
  "orderid": "ORDER123",
  "callback_url": "YOUR RETURN URL"
}

Success Response

{
  "status": true,
  "message": "Link successfully generated",
  "url": "upi://abc@upi/.....",
  "checkout": "https://api.finixpays.com/checkoutpage"
}

Callback

The gateway will POST the following JSON to your callback_url:

{
  "status": "success", // or "failed"
  "client_txn_id": "ORDER123",
  "utr": "123212233221",
  "amount": "100",
  "tax": "100"
}

🏧 Payout API (Wallet → Bank)

Initiate IMPS

Method	POST
Endpoint	`https://api.finixpays.com/api/payout/initiate`

{
  "token": "YOUR_TOKEN",
  "userid": "MID",
  "amount": "10",
  "mobile": "9999999999",
  "name": "Account Holder",
  "number": "0123456789",
  "ifsc": "HDFC0001234",
  "orderid": "ORDER456"
}

Success Response

{
  "status": true,
  "message": "Success",
  "id": "pout_OCL4oGW1P6dirP" (Optional)
}

Callback

The gateway will POST the following JSON:

{
  "status": "success", // or "failed" or "refund"
  "transaction_id": "ORDER456",
  "utr": "N12345678",
  "amount": "100",
  "fees": "2.45"
}

IP Whitelisting: Ensure your server IP is whitelisted in the Finixpay dashboard to receive payout callbacks.

📊 Status APIs

Pay‑In Status

POST https://api.finixpays.com/api/pg/phonepe/checkstatus
{
  "userid": "MID",
  "orderid": "ORDER123"
}

Success Response

{
  "status": "success",
  "message": "success!!",
  "client_txn_id": "333333333",
  "utr": "121212121212",
  "amount": "100.00"
}

Failed Response

{
  "status": "failed",
  "message": "Invalid Order Id!!"
}

Payout Status

POST https://api.finixpays.com/api/payout/checkstatus
{
  "userid": "MID",
  "orderid": "ORDER456"
}

Success Response

{
  "status": "success",
  "message": "",
  "utr": "N12345678",
  "client_txn_id": "ORDER456",
  "amount": "100.00",
  "tax": "10.00"
}

Refund Response

{
  "status": "refund",
  "message": "Invalid Order Id!!",
  "utr": "",
  "client_txn_id": "ORDER456"
}

Error Response

{
  "status": "failed",
  "message": "Invalid Order Id!!",
  "utr": "",
  "client_txn_id": "ORDER456"
}

Pay‑In Status

POST https://api.finixpays.com/api/pg/phonepe/checkstatus
{
  "userid": "MID",
  "orderid": "ORDER123"
}

Success Response

{
  "status": "success",
  "message": "success!!",
  "client_txn_id": "333333333",
  "utr": "121212121212",
}

Failed Response

{
  "status": "failed",
  "message": "Invalid Order Id!!"
}

📊 Wallet APIs

POST https://api.finixpays.com/api/wallet
{
  "userid": "MID",
  "token": "TOKEN"
}

Success Response

{
  "status": true,
  "message": "",
  "aeps": "00",
  "payin": "00",
  "payout": "00"
}

Failed Response

{
  "status": false,
  "message": "Userid invalid"//IP Restricted,Invalid Token,Userid Blocked
}

IP Whitelisting: Ensure your server IP is whitelisted in the Finixpay dashboard to receive Wallet data.

⚠️ Error Handling

FinixPay uses conventional HTTP status codes to indicate success or failure:

2xx – Request succeeded.
4xx – Client error (e.g., invalid parameters, authentication failed).
5xx – Server error (temporary). Retry with exponential back‑off.

For business logic errors, the status field in the JSON response will be false/failed and a descriptive message is provided.