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 navigate to Payment Settings within 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 admin panel settings field — it's stored encrypted, not in plain text.

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
• Webhook delivery — test mode webhooks fire exactly like live mode webhooks

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.

The only structural difference between test and live mode is which API key pair you use. Everything else — admin configuration, webhook setup, the payment flow — is identical. When you're ready to go live, you switch the key pair in BidKing's admin panel from test keys to live keys. That's it.

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:

• Key ID — paste your Razorpay Test Key ID here
• Key Secret — paste your Razorpay Test Key Secret here
• Currency — select INR (Indian Rupee). Razorpay India accounts process in INR by default; international currency support requires a separate Razorpay account type.
• Gateway label — the name displayed to buyers on the payment screen. Something like "Pay with Razorpay (UPI / Cards / Net Banking)" works well.
• Enable gateway — toggle this on to make Razorpay visible as a payment option at checkout.

Click Save. Razorpay should now appear as a payment method when a winning bidder proceeds to checkout.

Setting up webhooks

Webhooks are the most important — and most commonly skipped — part of any payment gateway integration. Here's why they matter: when a buyer completes a payment in Razorpay's popup and then closes their browser window before being redirected back to your site, the standard payment callback never fires. Without a webhook, that payment is never confirmed on BidKing's side, and the winning bid remains in "pending payment" state indefinitely — a frustrating experience for both the buyer and the auction operator.

Webhooks solve this by having Razorpay send a direct server-to-server HTTP POST to your platform whenever a payment event occurs. Even if the buyer's browser session ends, the webhook fires and BidKing marks the payment as complete.

To configure a webhook:

1. In your Razorpay Dashboard, go to Settings → Webhooks → Add New Webhook.
2. In the Webhook URL field, enter: https://yourdomain.com/webhook/razorpay (replace yourdomain.com with your actual domain).
3. Set a Webhook Secret — this is a string you create yourself, used to verify that incoming webhook requests actually come from Razorpay. Copy it; you'll need to enter it in BidKing's Razorpay settings.
4. Under Events, enable payment.captured at minimum. You can also enable payment.failed to trigger automated notifications when payments fail.
5. Click Save.

Back in BidKing's admin panel, enter the same Webhook Secret in the Razorpay settings. BidKing uses this to validate every incoming webhook signature before processing — an important security step that prevents fake payment confirmations.

Webhook configuration follows the same process in test mode and live mode — just ensure your webhook URL is accessible from the internet (not on localhost) and that it matches your live domain when switching to production.

Testing the integration end to end

Before treating the integration as complete, run a full transaction cycle from bid placement to payment confirmation:

1. Create a test auction with a starting bid of ₹1 and a short end time (5–10 minutes).
2. Open an incognito browser window, register a test buyer account, and place a winning bid.
3. After the auction closes, log in as the test buyer and proceed to payment.
4. On the payment screen, verify Razorpay appears as an option. Click it — the Razorpay checkout popup should open.
5. Use the test card 4111 1111 1111 1111 with any future expiry and any 3-digit CVV. Complete the payment.
6. After payment, verify the auction is marked as Payment Received in the BidKing admin panel.
7. Check that the buyer received a payment confirmation email.
8. In your Razorpay Test Dashboard, verify the transaction appears under Payments with status "Captured".

If all eight 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 → Payment Gateways → Razorpay, replace the Test Key ID and Test Key Secret with the corresponding Live values. Save.

Update your webhook URL if it was pointing to a test domain. The webhook secret can remain the same — Razorpay generates separate webhooks for test and live mode, and you'll need to create a new webhook entry in the Live mode section of the Razorpay Dashboard pointing to your production domain.

Run one real small-amount transaction (₹1 or the minimum auction amount on your platform) immediately after switching to live mode. Confirm it appears in your Razorpay Live Dashboard, that the money reaches your settlement account on the expected schedule (typically T+2 days for card payments, same-day for some UPI transactions), and that the confirmation email fires correctly.

Common issues and how to resolve them

Webhook signature mismatch

BidKing logs a signature mismatch error when the Webhook Secret in the admin panel doesn't match the secret configured in Razorpay. This most commonly happens after regenerating API keys — Razorpay also resets the webhook secret in some cases. Solution: go to Razorpay Dashboard → Webhooks, copy the current webhook secret, and paste it into BidKing's Razorpay settings. 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 auction order not updated

This almost always means the webhook is not configured or not reaching your server. Check: (1) webhook URL in Razorpay Dashboard is correct and uses https, (2) webhook secret matches in both places, (3) your server is accessible on the webhook URL (no firewall blocking inbound POST requests), (4) the payment.captured event is enabled on the webhook. Razorpay's Dashboard shows webhook delivery logs — check for failed deliveries and the error message they return.

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_.