Migration Guide

This guide helps you migrate your existing Chapa API v1 integration to v2.

Overview

Migrating from v1 to v2 involves updating:

• API endpoints
• Request/response formats
• Authentication headers
• Webhook payloads

Key Changes

Base URL

Payment Initialization

v1 Endpoint:

POST /v1/transaction/initialize

v2 Endpoint:

POST /v2/payments/hosted

Payment Verification

v1 Endpoint:

GET /v1/transaction/verify/{tx_ref}

v2 Endpoint:

GET /v2/payments/{reference}/verify

Migration Steps

1. Update API Base URL - Change from /v1 to /v2
2. Update Endpoint Paths - Use new v2 endpoint naming
3. Update Request Bodies - Adjust field names as needed
4. Update Webhook Handlers - Handle new v2 webhook payload structure
5. Test in Test Mode - Verify all flows work correctly
6. Switch to Live Mode - Deploy to production

Best Practices

• Test thoroughly in Test Mode before going live
• Update webhook handlers to accept both v1 and v2 formats during transition
• Monitor for any errors after migration
• Keep v1 documentation handy for reference

Need Help?

Contact Chapa support if you encounter any issues during migration.

Next Steps

• Quick Start - Get started with v2
• Accept Payments - v2 payment integration
• Webhooks - v2 webhook handling