Payment Gateway Integration in PHP: Step-by-Step Guide (2026)

Payment gateway integration in PHP looks more complicated than it is. Much of the integration complexity authentication, request handling, checkout components, and payment verification is handled through the gateway’s APIs and SDKs. What remains for the PHP developer is a clear sequence: install the SDK, create an order server-side, render the checkout on the frontend, verify the payment status on the backend, and handle webhooks for post-payment updates.

Get those five steps right, and the integration becomes easier to test, monitor, and maintain in production. The sections ahead walk through each one, cover UPI-specific integration, and flag the security mistakes that can create problems after go-live.

How Payment Gateway Integration in PHP Works

Before writing a line of code, understanding the data flow prevents the most common integration mistakes.

When a customer clicks pay, the sequence runs like this:

1. The PHP backend creates a unique order with the gateway API. The amount, currency, and reference ID are determined server-side so the frontend cannot manipulate the final order amount.
2. The frontend opens the gateway checkout using the payment session created for that order.
3. The customer completes the payment using an available payment method such as UPI, card, wallet, EMI, or net banking.
4. The gateway returns the customer to the configured return URL and provides payment information that your backend can use to check the payment status.
5. The gateway also sends asynchronous webhook events to your server. Your application verifies the webhook signature before processing the event and updating the order.

This flow makes current PHP integrations much shorter than older custom payment implementations because the SDK and checkout components handle much of the payment infrastructure while the application remains responsible for order creation, business logic, verification, and fulfilment.

Prerequisites: What the PHP Environment Needs

Before integration begins, the following must be in place:

• Merchant account: A live or sandbox account with Cashfree. Sandbox credentials allow you to test the integration without processing real transactions.
• Compatible PHP version: Use a PHP version supported by the current Cashfree PHP SDK. PHP 8.x is recommended for actively maintained projects.
• Composer: The standard PHP dependency manager used to install the Cashfree PHP SDK and its dependencies.
• cURL enabled: Required for server-to-gateway API communication. Check your PHP configuration to confirm it is active.
• HTTPS with a valid SSL certificate: Required for production payment and webhook endpoints. Local development can use localhost or a public tunnelling service for webhook testing.
• Basic familiarity with JSON: Gateway API responses arrive as JSON, making JSON parsing and response handling important parts of the integration.

Step-by-Step: Cashfree Payment Gateway Integration in PHP

The Cashfree PHP SDK handles much of the API request and response handling. The exact classes and methods can vary by SDK version, so always use the current version and syntax provided in the official Cashfree developer documentation.

Step 1: Create a Merchant Account and Get API Credentials

Sign up at Cashfree Payments and navigate to the developer dashboard. Create or access your sandbox credentials for testing. These credentials are used by the PHP backend to authenticate API calls.

Never commit API credentials to a public repository. Store them in environment variables or a secure secrets manager instead.

For production, keep sandbox and production credentials separate and configure the application environment accordingly.

Step 2: Install the Cashfree PHP SDK

Install the current Cashfree Payment Gateway PHP SDK using Composer:

composer require cashfree/cashfree-pg

The package name and installation command can change with SDK releases, so verify the current package and version in the official Cashfree developer documentation before installation.

After installation, include Composer’s autoloader in your PHP application:

require ‘vendor/autoload.php’;

Use the namespace and client configuration shown in the current Cashfree PHP SDK documentation for the SDK version installed in your project.

Developer note: Cashfree periodically updates its SDKs and APIs. If you are copying the code into a production project, use the current PHP SDK version and corresponding code examples from Cashfree Dev Studio rather than relying on an older SDK syntax.

Step 3: Create an Order Server-Side

When a customer initiates checkout, the PHP backend creates an order through the Cashfree API before payment details are collected.

This is important because the server should determine the final order amount rather than accepting an amount supplied by the browser.

A typical order contains:

• A unique order_id
• The final order_amount
• order_currency
• Customer details
• A configured return URL
• Other order metadata required by your application

The exact PHP request structure depends on the Cashfree SDK version being used. Follow the current SDK documentation for the order-creation method.

After the order is successfully created, Cashfree returns a payment session ID that can be passed to the frontend checkout.

Store the order_id against the customer’s cart or transaction record in your database before returning the payment session ID to the frontend.

Step 4: Render the Checkout (Frontend)

Pass the payment_session_id to the Cashfree JavaScript SDK on the checkout page.

A typical checkout flow uses the Cashfree JavaScript SDK in sandbox mode while testing and production mode after the application is ready for live transactions.

The Cashfree JS checkout handles the payment interface and supported payment methods. This means the PHP backend does not need to collect payment credentials directly.

For supported integrations, sensitive payment details are handled through Cashfree’s payment components rather than being collected directly by your PHP application.

Also read: How to Integrate a Payment Gateway in a Website or Application

Step 5: Verify Payment on the Backend

After the customer completes payment, Cashfree can redirect the customer to the configured return_url.

Do not treat the redirect itself as proof that the payment succeeded.

Instead, use the Cashfree API to retrieve the payment/order status from your backend and update the order only after the status has been verified.

A simplified application flow is:

Get the order_id from the return request.

Retrieve the payment status from Cashfree using the server-side SDK/API.

If the verified payment status is PAID:

• Update the order status in the database.*
• Trigger fulfilment or service delivery.*
• Send the confirmation to the customer.*

Otherwise:

• Handle the pending, failed, or expired state according to your application logic.*

The exact SDK method depends on the version of the Cashfree PHP SDK being used.

Never rely solely on redirect parameters or frontend state to confirm a successful payment.

Step 6: Handle Webhooks

Cashfree sends webhook events to a configured URL when payment-related events occur. Webhooks are particularly important when a customer’s browser closes, loses connectivity, or does not return to the website after completing payment.

Your webhook endpoint should:

1. Read the raw request body.
2. Extract the webhook signature and timestamp from the request headers.
3. Verify the signature using Cashfree’s recommended verification process.
4. Parse and validate the event.
5. Check the relevant order/payment information.
6. Update the database idempotently.
7. Return an appropriate HTTP response after processing.

A simplified webhook flow looks like this:

$rawBody = file_get_contents('php://input');

Read the Cashfree webhook signature and timestamp from the request headers.

Verify the webhook using the current Cashfree SDK or recommended webhook verification method.

If the signature is valid:

• Parse the JSON payload.*
• Identify the order and payment event.*
• Update the order status if the event is valid and has not already been processed.*
• Return HTTP 200.*

If the signature is invalid:

• Reject the request.*

Webhook verification should use the raw request body. Do not modify, reformat, or decode and re-encode the payload before signature verification.

UPI Payment Gateway Integration in PHP

UPI integration follows the same core sequence of server-side order creation, payment session generation, checkout, payment-status verification, and webhook processing.

The difference is the payment method selected during checkout.

• UPI Intent: Where supported and enabled, customers can select a UPI app and continue the payment through the supported UPI flow. No separate PHP order-creation flow is required just because the customer is paying through UPI.
• UPI Collect: Where supported in the configured checkout, customers can enter their UPI ID and complete the payment request through the supported UPI flow.
• UPI AutoPay: For recurring payments, use Cashfree’s subscription and mandate capabilities rather than treating recurring UPI payments as a standard one-time checkout. The subscription flow has its own APIs and webhook events for mandate and payment status tracking.

For UPI, use the test credentials and payment scenarios provided in the current Cashfree sandbox documentation. Live UPI transactions use your production Cashfree setup and credentials.

Common Errors and Fixes in PHP Payment Gateway Integration

Most PHP integration failures come down to a few common issues. The following are some of the most frequent problems and their solutions.

• Signature issue while verifying webhooks: This can happen because of an incorrect secret, modified request body, incorrect header handling, or improper signature verification. Always follow Cashfree’s current webhook verification method and use the raw request body.
• Webhook fails to fire while testing: Webhooks require a publicly reachable endpoint. During local development, use a secure tunnelling solution such as ngrok or another equivalent service.
• Order amount differs from payment amount: Determine the final order amount on the server and compare payment information against the server-side order rather than trusting the amount supplied by the client.
• Order already paid error on retry: Check the current order/payment status before attempting a new payment flow. Your application should distinguish between pending, paid, failed, and expired states.
• Duplicate webhook processing: Webhooks can be retried. Store the relevant event/order information and make your processing logic idempotent so the same event does not trigger duplicate fulfilment.
• cURL SSL errors: Check the server’s CA certificate bundle and PHP/OpenSSL configuration. Outdated hosting environments can cause HTTPS API requests to fail.
• Sandbox and production mismatch: Confirm that the API credentials, SDK environment, webhook configuration, and frontend checkout mode all belong to the same environment.

Conclusion

Payment gateway integration in PHP comes down to a reliable sequence: create the order server-side, render the checkout using the gateway’s JavaScript SDK, verify payment status on the backend, and handle webhooks for asynchronous status updates.

UPI integration follows the same core flow without requiring a separate PHP payment integration. The most important security practices are keeping credentials server-side, determining the order amount on the backend, verifying payment status before fulfilment, and validating webhook signatures before processing events.

Cashfree provides a PHP Payment Gateway SDK, sandbox testing, developer tools, and support for a wide range of payment methods including UPI, cards, EMI, wallets, and net banking.

FAQs

How do I integrate a payment gateway in PHP for a website?

Install the gateway’s PHP SDK using Composer, create an order server-side, open the hosted checkout using the payment session ID, and verify the payment status from your backend before fulfilling the order.

How does Cashfree Payment Gateway integration work in PHP?

Install the current Cashfree PHP SDK, configure your sandbox or production credentials, create an order from your PHP backend, pass the resulting payment session ID to Cashfree Checkout, and verify payment status through the server-side API. Webhooks can then be used to receive asynchronous payment updates.

How do I integrate UPI payment in a PHP website?

UPI can be handled through the Cashfree checkout flow along with other supported payment methods. Your PHP backend follows the same order creation and payment-status verification process rather than requiring a completely separate UPI integration.

Why is server-side payment verification important in PHP?

Frontend redirect parameters should not be treated as proof of successful payment. Server-side verification allows your application to confirm the actual payment status before fulfilling an order.

How do I handle payment webhooks in PHP?

Read the raw request body, extract the required webhook headers, verify the webhook signature using Cashfree’s recommended method, process the event only after successful verification, and make the handler idempotent so duplicate events do not result in duplicate fulfilment.

What PHP version is required for payment gateway integration?

The required PHP version depends on the version of the Cashfree PHP SDK you use. Check the current SDK compatibility requirements before installation. Composer and cURL should also be available in the PHP environment.

Can I test PHP payment gateway integration without going live?

Yes. Cashfree provides a sandbox environment for testing payment integrations before moving to production. Use the current test credentials and payment details provided in the Cashfree developer documentation.

How do I debug a payment gateway not working in PHP?

Check the API error response, confirm that the credentials match the environment, verify the payment and webhook configuration, check the server’s SSL/cURL configuration, and use Cashfree’s developer tools and transaction logs to trace the integration.