Panapay Payment Gateway API (v2)

Authentication

API Key Setup

• Include API-KEY header in all requests
• Whitelist your server/proxy IP for security
• Contact admin for test and live API keys

Important

Requests from unregistered IPs will be blocked (error code 1010). Test API Key marks transactions as test. Live API Key processes live transactions.

Transaction Statuses

📥 Deposit Statuses

Status	Description
`pending`	Payment link generated but user hasn't paid or provided RRN/UTR
`processing`	Payment submitted, pending Panapay approval
`approved`	Payment approved (final)
`rejected`	Payment failed (wrong RRN/UTR or settlement failed)
`abandoned`	User didn't initiate payment within 24 hours

📤 Withdrawal Statuses

Status	Description
`processing`	Withdrawal initiated and being processed
`approved`	Funds paid out (final)
`rejected`	Withdrawal failed due to invalid details or other issues

🔄 Host-to-Host (H2H) vs Hosted Payment

Host-to-Host (H2H: true)

• Merchant receives payment details (QR code/link)
• Users stay on merchant's platform
• Response includes qr_code (base64) and or link (UPI), bank account details (NetBanking)
• For UPI/NetBanking deposits only

Hosted Payment (H2H: false)

• Users are redirected to Panapay payment page
• Simpler integration for merchants
• Response includes payment link to redirect users
• Default flow if H2H not specified

Note: Withdrawal transactions (gateway 3) ignore the H2H parameter and always follow the standard processing flow.

💳 Deposit

Initialize Payment

POST /initialize

Required Headers

              API-KEY: YOUR-API-KEY

              Content-Type: application/json

Base URL

https://gate.panapay.in/api/v1/

Request Body Fields

Field	Type	Required	Description
`reference_id`	String	Yes	Merchant's unique transaction ID
`currency`	String	Yes	Currency code. Only `INR` supported
`amount`	Integer	Yes	Transaction amount (in smallest unit or as integer depending on integration)
`transaction_type`	String	Yes	`deposit` or `withdrawal`
`gateway`	String	Yes	Gateway code: `1`=NetBanking, `2`=UPI, `3`=Withdrawal
`h2h`	Boolean	Optional	If `true` returns payment details for host-to-host integration. Default: `false`
`callback_url`	String	Optional	URL to receive transaction status updates
`redirect_url`	String	Optional	URL to redirect user after hosted payment
`user_id`	String	Yes	User ID from merchant
`user_full_name`	String	Yes	Customer's full name
`phone_number`	String	Yes	Customer phone
`bank_name`	String	Conditional	Required for NetBanking/Withdrawal
`account_number`	String	Conditional	Required for NetBanking/Withdrawal
`bank_ifsc`	String	Conditional	IFSC code for bank transfers/withdrawals

🏛️ NetBanking

Gateway 1

Example Request (H2H: true)

{
  "reference_id": "1969768999e99999",
  "currency": "INR",
  "amount": 1700,
  "transaction_type": "deposit",
  "gateway": "1",
  "h2h": true,
  "user_id": "595949",
  "user_full_name": "Emma James",
  "phone_number": "0819436262",
  "bank_name": "Diamond Bank",
  "account_number": "3395584382",
  "bank_ifsc": "54984895",
  "callback_url": "https://merchant.example.com/callback"
}

H2H Response

{
  "message": "success",
  "status": 201,
  "data": {
    "amount": "1700.00",
    "transaction_hash": "1e00aae8465aae9c5bab322b45...af3b",
    "payment_details": {
      "bank_name": "Diamond Bank",
      "account_name": "Emma James",
      "account_number": "3395584382",
      "ifsc": "54984895",
    }
  }
}

📱 UPI

Gateway 2

Example Request (H2H: true)

{
  "reference_id": "297676899999",
  "currency": "INR",
  "amount": 2000,
  "transaction_type": "deposit",
  "gateway": "2",
  "h2h": true,
  "user_id": "595950",
  "user_full_name": "John Doe",
  "phone_number": "09012345678",
  "callback_url": "https://merchant.example.com/callback"
}

H2H Response

{
  "message": "success",
  "status": 201,
  "data": {
    "amount": "2000.00",
    "transaction_hash": "somehashvalue456",
    "payment_details": {
      "qr_code": "base64-encoded-qr-string",
      "link": "UPI-REDIRECT-LINK-HOLDER",
      "paytm_link": "PAYTM-REDIRECT-LINK-HOLDER",
      "phonepe_link": "PHONEPE-REDIRECT-LINK-HOLDER",
      "googlepay_link": "GOOGLEPAY-REDIRECT-LINK-HOLDER"
    }
  }
}

🌐 Hosted Payment Example (H2H: false or omitted)

Request

{
  "reference_id": "3976768999e99999",
  "currency": "INR",
  "amount": 2500,
  "transaction_type": "deposit",
  "gateway": "2",
  "user_id": "595952",
  "user_full_name": "Alice Johnson",
  "phone_number": "08123456790",
  "callback_url": "https://merchant.example.com/callback",
  "redirect_url": "https://merchant.example.com/return"
}

Response

{
  "message": "success",
  "status": 201,
  "data": {
    "amount": "2500.00",
    "transaction_hash": "somehashvalue789",
    "payment_details": {
      "link": "https://panapay.in/payment/transaction_hash"
    }
  }
}

With hosted payments, redirect your users to the provided link to complete payment on Panapay's secure payment page.
For H2H, payment details (UPI IDS, redirect links, bank accounts) are valid only for 10 minutes.

💸 Withdrawal

Note: Withdrawal transactions (gateway 3) ignore the H2H parameter and always respond with a processing status initially.

Request Example

{
  "reference_id": "4976768999e99999",
  "currency": "INR",
  "amount": 1500,
  "transaction_type": "withdrawal",
  "gateway": "3",
  "user_id": "595951",
  "user_full_name": "Jane Smith",
  "phone_number": "08123456789",
  "bank_name": "Axis Bank",
  "account_number": "1122334455",
  "bank_ifsc": "UTIB0000222",
  "callback_url": "https://merchant.example.com/callback"
}

Response Example

{
  "message": "success",
  "status": 201,
  "data": {
    "amount": "1500.00",
    "transaction_hash": "somewithdrawalhash123",
    "withdrawal_status": "processing"
  }
}

🔍 Check Transaction Status

Endpoint

GET /check-transaction/{reference_id}

Response Example

{
  "message": "success",
  "status": 200,
  "data": {
    "status": "approved",
    "paid_amount": "1700.00",
    "expected_amount": "1700.00",
    "rrn": "76543456776",
  }
}

🔔 Callback Data

When a transaction is approved, Panapay sends a POST request to your provided callback_url. The callback payload contains the details below. For deposit transactions, the rrn field will always be present. For withdrawals, rrn may be omitted if not applicable.

Headers

• Content-Type: application/json
• User-Agent: Panapay server — you can use this to help verify callbacks

Response Required

Your server must respond with the exact text 'success' and HTTP status 200 after processing the callback.

POST Body Fields

Field	Type	Required	Description
`reference_id`	string	Yes	Merchant's unique transaction ID
`status`	string	Yes	Transaction status — always `approved` for callbacks
`amount`	integer	Yes	Amount in smallest currency unit (integer)
`rrn`	string	Conditional	Payment reference (UTR/RRN). Sent for all deposits; optional for withdrawals.

Example Callback — Deposit

{
  "reference_id": "t476545456",
  "status": "approved",
  "amount": 170000,
  "rrn": "UTR1234567890"
}

Example Callback — Withdrawal

{
  "reference_id": "1969768999e99999",
  "status": "approved",
  "amount": 180000
}

Example cURL

curl -X POST "https://merchant.example.com/callback" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Panapay server" \
  -d '{"reference_id":"t476545456","status":"approved","amount":170000,"rrn":"UTR1234567890"}'

Security tip: Verify callbacks by checking against our SERVER IP address. Contact Panapay for that. If you miss a callback or need to check a transaction, use the /status/{reference_id} endpoint.

⚠️ Error Codes

🔐 Authentication & Whitelisting

1007 Empty API key

1008 Invalid API key

1009 Disabled merchants can't access endpoint

1010 IP address not whitelisted

🔧 Request / Processing Errors

2000 Invalid / missing request body data

2001 Missing required bank details

2077 Error creating upstream transaction

300 General validation / incomplete transaction payloads

7801 Payment channel not set yet, contact support

🌐 HTTP-style Codes

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error