Chapa Payment Gateway API Integration in PHP

What Is Chapa Payment Gateway and How Its API Works in PHP

Online payments are a critical component of modern web applications. If you are targeting users in Ethiopia or Africa, Chapa Payment Gateway is one of the most reliable and developer-friendly payment solutions available today. In this tutorial, you will learn how to integrate the Chapa Payment Gateway API in PHP from scratch. This guide covers:

• Payment initialization
• Payment verification
• Webhooks and callbacks
• Securing API keys
• Testing success, failure, and edge cases
• Writing clean, maintainable, and documented PHP code

This article is suitable for beginners, intermediate PHP developers, and freelancers building real-world payment systems.

What Is Chapa Payment Gateway API?

Chapa is a digital payment platform that allows businesses to accept payments via:

• Bank transfers
• Mobile money
• Cards
• Local payment methods

Chapa provides a RESTful API that is easy to integrate with PHP, Laravel, WordPress, and other platforms.

Prerequisites for Chapa Payment Gateway API Integration

Before starting, ensure you have:

• PHP 7.4 or higher
• A web server (Apache / Nginx / XAMPP)
• cURL enabled in PHP
• Basic knowledge of PHP and JSON
• A Chapa merchant account

Step 1: Create a Chapa Merchant Account

1. Visit the Chapa website
2. Register as a merchant
3. Access your Dashboard
4. Copy your:
   1. Public Key
   2. Secret Key

⚠️ Never expose your Secret Key in frontend JavaScript or public repositories.

Step 2: Secure Your API Keys (Best Practice)

Create a configuration file to store your Chapa keys securely.
config.php

Step 3: Payment Flow Overview

Understanding the flow is critical:

1. User clicks Pay Now
2. Backend initializes payment with Chapa
3. User is redirected to Chapa checkout
4. Payment is completed or failed
5. Chapa redirects to callback URL
6. Backend verifies transaction
7. Order is confirmed or rejected

Step 4: Initialize Payment with Chapa API

Required Parameters

• amount
• currency (ETB or USD)
• email
• first_name
• last_name
• tx_ref (unique transaction reference)
• callback_url
• return_url

initialize_payment.php

Step 5: Handle Callback / Return URL

Chapa redirects the user after payment, but never trust frontend redirects alone.
success.php

Step 5: Handle Callback / Return URL

Always verify payment server-to-server.
verify_payment.php

✔ Check amount, currency, and tx_ref before confirming order
✔ Prevent duplicate processing

Step 7: Implementing Chapa Webhooks in PHP for Reliable Payment Confirmation

Webhooks ensure you receive payment updates even if the user closes the browser.
Set Webhook URL in Chapa Dashboard
Example:
https://yourdomain.com/webhook.php

webhook.php

Step 8: Testing Chapa Payment Gateway API Integration in PHP (Sandbox Mode)

Chapa provides test keys.
Set Webhook URL in Chapa Dashboard

Test Scenarios for Chapa Payments API

Step 9: Security Best Practices

1. 1. Never expose secret keys in JavaScript
   2. Validate payment amount and currency
   3. Use HTTPS only
   4. Store transaction references securely
   5. Protect webhook endpoint
   6. Log all API responses for debugging

Step 10: Common Errors and Fixes

Invalid API Key
✔ Ensure correct environment key (test vs live)

Payment Redirect Works but Not Verified
✔ Missing verification step
✔ Wrong tx_ref

Duplicate Payments
✔ Mark transactions as processed in database

Conclusion

Integrating the Chapa Payment Gateway API in PHP is straightforward when you follow best practices. By properly initializing payments, verifying transactions, handling callbacks and webhooks, and securing your API keys, you can build a robust and production-ready payment system.

This guide provides everything you need—from basic setup to advanced security considerations—to confidently deploy Chapa payments in real-world PHP applications.

I can also provide:

• Laravel version
• WordPress plugin integration