ConnectX
Docs
Introduction

Documentation

Learn how to integrate ConnectX into your application.

Chapa Payment Integration

Learn how to integrate and use Chapa payments in ConnectX

Chapa is a payment gateway that allows you to accept payments from customers in Ethiopia and other African countries. ConnectX provides a seamless integration with Chapa to handle online payments for your orders.

  • Support for multiple payment methods (bank transfers, mobile money, cards)
  • Secure payment processing with encryption
  • Real-time payment status updates
  • Automatic order status updates after successful payment
  • Support for both test and production environments
  1. Initialize Payment: Call the initialize endpoint with order details to get a checkout URL
  2. Redirect Customer: Redirect the customer to the Chapa checkout page using the provided URL
  3. Handle Callback: Chapa will redirect back to your return_url after payment completion
  4. Verify Payment: Verify the payment status using the transaction reference
  1. Customer places an order on your platform
  2. Your system calls the initialize payment endpoint
  3. Customer is redirected to Chapa checkout page
  4. Customer completes payment on Chapa
  5. Chapa redirects back to your return_url
  6. Your system verifies the payment status
  7. Order status is updated based on payment result

Available Endpoints

  • POST /payments/initialize_chapa_payment/ - Initialize a new payment
  • POST /payments/verify_chapa_payment/ - Verify payment status

Common Error Scenarios

  • Invalid order ID or amount
  • Network connectivity issues
  • Payment timeout or cancellation
  • Invalid transaction reference

Error Response Format

{
  "status": "error",
  "message": "Error message describing the issue",
  "code": "ERROR_CODE"
}

Test Environment

ConnectX provides a test environment for Chapa integration. Use the following test credentials:

  • Test Card Number: 4242 4242 4242 4242
  • Expiry Date: Any future date
  • CVV: Any 3 digits
  • OTP: 123456

Initialize a new payment transaction with Chapa payment gateway

Command

curl -X POST 'https://connectx-backend-4o0i.onrender.com/api/payments/initialize_chapa_payment/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "phone_number": "+251912345678",
    "return_url": "https://your-frontend.com/payment-complete"
  }'

Response

{
  "status": "success",
  "message": "Payment initialized successfully",
  "data": {
    "payment_id": "123e4567-e89b-12d3-a456-426614174004",
    "checkout_url": "https://checkout.chapa.co/checkout/payment/1234567890",
    "tx_ref": "TX-1234567890ABCDEF"
  }
}

Verify the status of a Chapa payment transaction

Command

curl -X POST 'https://connectx-backend-4o0i.onrender.com/api/payments/verify_chapa_payment/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tx_ref": "TX-1234567890ABCDEF"
  }'

Response

{
  "status": "success",
  "message": "Payment verified successfully",
  "payment": {
    "id": "123e4567-e89b-12d3-a456-426614174004",
    "order": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "ORD-2024-001",
    "amount": "1999.98",
    "payment_method": "chapa",
    "status": "completed",
    "transaction_id": "TX-1234567890ABCDEF",
    "verification_data": {
      "status": "success",
      "message": "Payment verified successfully",
      "data": {
        "id": "1234567890",
        "tx_ref": "TX-1234567890ABCDEF",
        "amount": "1999.98",
        "currency": "ETB",
        "status": "success"
      }
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}