ConnectX
Docs
Introduction

Documentation

Learn how to integrate ConnectX into your application.

Payments API Overview

Learn how to interact with the ConnectX Payments API

The Payments API allows you to manage payments in your ConnectX store. You can initialize payments, verify transactions, and handle both Chapa online payments and Cash on Delivery orders.

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

All API endpoints are relative to the base URL:

https://connectx-backend-4o0i.onrender.com/api

Payments

  • GET /payments/ - List all payments
  • POST /payments/initialize_chapa_payment/ - Initialize Chapa payment
  • POST /payments/verify_chapa_payment/ - Verify Chapa payment
  • POST /payments/{id}/confirm_cod_payment/ - Confirm Cash on Delivery payment

Chapa Online Payment

Chapa is our primary online payment gateway. It supports various payment methods including bank transfers, mobile money, and credit/debit cards. The payment flow consists of:

  1. Initialize payment with order details
  2. Redirect customer to Chapa checkout page
  3. Verify payment status after completion

Cash on Delivery (COD)

For Cash on Delivery orders, the payment is confirmed by the tenant owner after receiving the payment from the customer. The confirmation process includes:

  1. Create order with COD payment method
  2. Deliver order to customer
  3. Confirm payment receipt through the API

Get a list of all payments

Command

curl -X GET 'https://connectx-backend-4o0i.onrender.com/api/payments/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": "123e4567-e89b-12d3-a456-426614174001",
      "order_number": "ORD-2024-001",
      "amount": "1999.98",
      "payment_method": "chapa",
      "status": "pending",
      "transaction_id": "TX-1234567890ABCDEF",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174002",
      "order": "123e4567-e89b-12d3-a456-426614174003",
      "order_number": "ORD-2024-002",
      "amount": "1499.99",
      "payment_method": "cod",
      "status": "completed",
      "transaction_id": "COD-2024-002",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z"
    }
  ]
}

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"
  }
}

Confirm receipt of payment for Cash on Delivery orders (Tenant Owner only)

Command

curl -X POST 'https://connectx-backend-4o0i.onrender.com/api/payments/123e4567-e89b-12d3-a456-426614174002/confirm_cod_payment/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "confirmation_note": "Payment received in cash"
  }'

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "order": "123e4567-e89b-12d3-a456-426614174003",
  "order_number": "ORD-2024-002",
  "amount": "1499.99",
  "payment_method": "cod",
  "status": "completed",
  "transaction_id": "COD-2024-002",
  "created_at": "2024-01-02T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z"
}