Verify Payments

Payment verification is how you confirm the final status of a transaction after a customer attempts to pay.

You should verify a payment when:

• The customer returns from checkout (redirect or inline completion)
• You receive a webhook event and want to double-check (optional)
• You must confirm payment status before delivering goods/services

Endpoint

GET /v2/payments/{reference}/verify
Host: api.chapa.co

Authentication

Headers

Example:

Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

Path Parameter

Example Request

GET https://api.chapa.co/v2/payments/CHAPA123456789/verify
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

Example Response

{
  "status": "success",
  "message": "Payment retrieved successful",
  "data": {
    "chapa_reference": "CHAPA123456789",
    "merchant_reference": "Cv90J9DZ8r6zKW",
    "amount": 25000,
    "currency": "ETB",
    "status": "success",
    "payment_method": "card",
    "service_fee": 350,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "251722927727"
    },
    "created_at": "2025-11-07T11:06:00Z",
    "updated_at": "2025-11-08T11:08:00Z"
  }
}

Response Fields

Top-Level Fields

Payment Object (data)

How to Use Verification in Your App

Typical Flow

1. Initialize payment → get checkout URL
2. Customer completes checkout
3. Your backend calls /verify
4. Handle the response:
   • If data.status == "success" → fulfill order / grant access
   • If data.status == "pending" → wait for webhook or retry verification
   • If data.status == "failed" | "cancelled" | "incomplete" | "blocked" → show error, allow retry if applicable

Recommended Verification Rules

Treat a payment as successful only when:

• data.status == "success"
• Amount and currency match what you expected
• The payment belongs to your merchant account

Store these for reconciliation:

• chapa_reference
• merchant_reference
• amount, currency
• payment_method
• service_fee
• created_at, updated_at
• customer (if available)

If you receive a webhook event:

• Use it as a real-time signal to update state
• Optionally verify once more for confirmation (useful for high-value orders)

Common Errors

Failed Response

If the reference is invalid or the payment cannot be found:

{
  "status": "error",
  "message": "Payment not found",
  "error": {
    "code": "NOT_FOUND",
    "details": null
  }
}

Recommended handling:

• Confirm you're verifying with the correct reference (Chapa reference, not your merchant reference)
• Ensure you're using the correct environment keys (test key for test payments, live key for live payments)
• If you just created the payment, retry verification after a short delay (your system should be resilient to temporary states)

Verification Checklist

Before you mark an order as paid, confirm all of the following on your server:

Next Steps

• Accept Payments - Full hosted payment integration
• Webhooks - Real-time payment notifications
• Quick Start - End-to-end payment flow