How to Integrate Razorpay With Your PHP Auction Script

Prerequisites

Before starting the integration, make sure you have the following in place:

• A Razorpay account — free to create, but business KYC is required before the live mode is activated. Test mode is available immediately after registration.
• BidKing installed and running — the auction script should be live on your domain with admin panel access. If you haven't installed BidKing yet, the setup guide walks through the full process.
• Admin panel access — you'll need to open Settings › Payment Gateways in the BidKing admin panel to complete the configuration.

Razorpay works in two modes: test mode (for development and configuration verification, no real money moves) and live mode (production, real transactions). Always configure test mode first and run complete end-to-end tests before switching to live. This guide covers both.

Creating your Razorpay account

Go to razorpay.com and sign up for a new account. The registration itself is immediate — just an email address and password. After registration you'll have immediate access to test mode, which is all you need to start configuration.

To unlock live mode, you need to complete business verification (KYC). Razorpay requires the following documents for Indian businesses:

• GST certificate — if your business is GST-registered. Businesses below the GST threshold can use PAN instead.
• PAN card — business PAN or proprietor PAN depending on your business structure.
• Bank account details — cancelled cheque or bank statement showing your account number and IFSC code. This is where Razorpay will deposit settlement amounts.
• Business address proof — utility bill, rental agreement, or similar document.

Razorpay's typical KYC processing time is 2–5 business days after documents are submitted. In practice, many accounts are verified within 24–48 hours. You can start building and testing in test mode during this period — live mode activation is a separate step you trigger once KYC is approved.

Getting your API keys

API keys are the credentials that connect BidKing to your Razorpay account. In your Razorpay Dashboard, navigate to Settings → API Keys.

You'll see two sets of keys: Test and Live. Start with the Test keys. Click Generate Test Key (if you haven't already) — Razorpay will show you a Key ID and a Key Secret. These are displayed together only once; if you lose the Key Secret you'll need to regenerate the pair.

Two critical security notes:

• The Key ID is public. It appears in client-side JavaScript on your payment page and that's fine — it's designed to be visible.
• The Key Secret is private. It must never appear in client-side code, public files, or version control. It lives only in your server-side configuration, which in BidKing means the Secret Key field in the admin panel. It's saved in your database and never printed back into the form — the box shows empty after saving, and leaving it empty keeps the saved value.

Copy both values somewhere secure temporarily — you'll need them in the next step.

Test mode vs live mode — what's actually different

Razorpay's test mode is a complete sandbox: you can simulate any payment outcome without moving real money. This includes testing:

• Successful card payments using Razorpay's test card numbers
• Failed payments (to verify your platform handles payment failures gracefully)
• UPI payments using Razorpay's test UPI ID (success@razorpay)
• Net banking simulations

Razorpay's standard test card: 4111 1111 1111 1111, any future expiry date, any 3-digit CVV. For UPI, the test VPA is success@razorpay. Use these for every test transaction — do not use real card or bank details in test mode.

On the Razorpay side, the difference between test and live mode is which API key pair you use. BidKing works the same way: Razorpay's Mode reads Set by your keys, so test keys take test payments and live keys take real money. There's no separate switch to change.

Configuring Razorpay in the BidKing admin panel

Log into your BidKing admin panel and navigate to Settings › Payment Gateways → Razorpay.

You'll see the following configuration fields:

• Public Key — paste your Razorpay Test Key ID here
• Secret Key — paste your Razorpay Test Key Secret here
• Currency — the 3-letter code Razorpay charges in. It starts as INR (Indian Rupee), but switches once to your store's currency if Razorpay accepts it. Unless your Razorpay account takes international payments, set it to INR; prices in another store currency are then converted at a saved exchange rate or a fixed rate you set, and with neither, Razorpay is hidden at checkout.
• Fixed rate — optional; used to convert prices only when there's no saved exchange rate.
• Logo at checkout — optional; the image buyers see next to the Razorpay option.

Click Save. Back on the Payment Gateways list, switch Razorpay on so it shows at checkout. Razorpay should now appear as a payment method when a customer tops up their wallet or checks out from the cart.

How payment confirmation works

BidKing's Razorpay integration doesn't use webhooks, so there's nothing to set up in Razorpay's Webhooks settings. When a buyer pays, BidKing creates a Razorpay order for the exact amount and opens Razorpay's checkout popup. When the payment succeeds, the page sends the result to /payment-gateway/razorpay/verify.php on your site, which:

1. Verifies the Razorpay payment signature using your Secret Key, so a forged confirmation is rejected.
2. Checks that the Razorpay order is the one BidKing created for this payment.
3. Asks Razorpay for the payment and confirms it is captured, for the same amount BidKing expected.

Only then are the coins credited or the order placed.

What if the buyer closes the browser?

Because confirmation runs from the buyer's browser, a buyer who pays and closes the window before that step finishes leaves the payment request Pending in BidKing even though Razorpay captured the money. Open Finance › Transactions › Payment Requests and use Check with gateway on the pending request. If Razorpay confirms a captured payment for the same amount and currency, the request is settled and the coins or order are delivered; anything else is shown to you and nothing changes. If the check can't settle it, look the payment up in your Razorpay Dashboard and settle it with the customer. If the request had already closed when the payment came in, it's listed under Paid, not ordered, for you to refund or fulfil, and the buyer's result page says the payment is held for review, so they don't pay again.

Testing the integration end to end

In BidKing, bids are paid with a bid fee from the customer's wallet, so Razorpay comes into play in two places: when a customer tops up their wallet, and when a winner claims a won item through the cart at the winning price. Test both:

1. Open an incognito browser window and register a test buyer account.
2. Open the wallet and top it up. On the payment screen, verify Razorpay appears as an option. Click it — the Razorpay checkout popup should open.
3. Use the test card 4111 1111 1111 1111 with any future expiry and any 3-digit CVV. Complete the payment.
4. Verify the coins appear in the test buyer's wallet, and the payment shows as Paid under Finance › Transactions › Payment Requests in the admin panel.
5. Create a test auction with a starting bid of ₹1 and a short end time (5–10 minutes), and place a bid from the test account.
6. After the auction ends and the winner is declared (this runs on cron, so cron must be set up), claim the item from the cart as the test buyer and pay with Razorpay again.
7. In your Razorpay Test Dashboard, verify both transactions appear under Payments with status "Captured".

If all seven steps complete successfully, your integration is working correctly. Test the UPI flow as well using success@razorpay as the test UPI ID — UPI is typically the preferred payment method for Indian buyers and it's worth confirming the entire UPI flow before going live.

Going live with Razorpay

Once KYC is approved and you've completed testing, switching to live mode is a two-step process:

1. In Razorpay Dashboard → Settings → API Keys, generate your Live API Keys. Copy the Live Key ID and Live Key Secret.
2. In BidKing admin → Settings › Payment Gateways → Razorpay, replace the Public Key and Secret Key with the corresponding Live values. Save. The live keys are what switch it to real payments.

Run one real small-amount transaction (for example a minimum wallet top-up) immediately after switching to live mode. Confirm it appears in your Razorpay Live Dashboard, that the coins reach the wallet, and that the money reaches your settlement account on the expected schedule (typically T+2 days for card payments, same-day for some UPI transactions).

Common issues and how to resolve them

"Signature verification failed"

The payment signature is checked with the Secret Key saved in BidKing, so a mismatch means that key doesn't belong to the Key ID that took the payment. Common causes: the Secret Key was regenerated in Razorpay and not updated in BidKing, or the Public Key and Secret Key come from different pairs (one test, one live). Paste a matching pair, save and retest.

UPI payment method not showing in checkout

UPI must be explicitly enabled in your Razorpay account under Settings → Payment Methods. If you created your account recently, UPI may be enabled by default; if it's not showing on your checkout, check this setting. UPI also requires that the buyer's device has a UPI-linked bank account registered.

Payment captured but still pending in BidKing

The confirmation step never reached your site — usually because the buyer closed the browser or lost connection right after paying. The payment request stays Pending under Finance › Transactions › Payment Requests, until your store asks Razorpay about it itself about 3 days after its payment page ran out (and closes it at 14 days whatever the answer). Use Check with gateway on it first; if that can't settle it, check the Paid, not ordered tab, then match it against the payment in your Razorpay Dashboard and settle it with the customer.

Test transactions appearing in live dashboard

You're using live API keys in a test environment, or the BidKing admin panel still has test keys configured when you intended to use live. Verify which key pair is active in BidKing's Razorpay settings. Test Key IDs start with rzp_test_; Live Key IDs start with rzp_live_.

Common questions

Does BidKing's Razorpay integration need webhooks?

No. Confirmation runs from the buyer's browser: the site verifies Razorpay's payment signature, checks the order and confirms with Razorpay that the payment was captured for the expected amount.

What happens if a buyer pays and closes the browser too early?

The payment request can stay Pending in BidKing, because confirmation runs from the browser. Open Finance › Transactions › Payment Requests and use “Check with gateway” on the pending request: if Razorpay confirms a payment for the same amount and currency, the request is settled and fulfilled. If the request had already closed, the payment is listed under Paid, not ordered, for you to refund or fulfil. Otherwise, look the payment up in your Razorpay Dashboard and settle it with the customer.

Can I test Razorpay before going live?

Yes. Save your Razorpay test keys in BidKing, run a full purchase, then switch to live keys once Razorpay has approved your business verification.

Which currency does BidKing charge in with Razorpay?

The currency set on the Razorpay gateway. It starts as INR, but switches once to your store's currency if Razorpay accepts it. Unless your Razorpay account takes international payments, set it to INR; prices in another store currency are then converted at a saved exchange rate or a fixed rate you set, and with neither, Razorpay is hidden at checkout.