Authorize Payment

Some Direct Charge payments require additional customer authentication before they can be completed. This step is called Authorization.

Authorization is required when the payment provider needs the customer to confirm the transaction using:

• PIN
• OTP (One-Time Password)
• USSD confirmation
• Other provider-specific authentication steps

Chapa notifies you that authorization is required via:

• The Direct Charge response (auth_type)
• A webhook event (payment.auth_needed)

When Authorization Is Required

After initiating a direct charge, you may receive a response such as:

{
  "auth_type": "PIN"
}

or

{
  "auth_type": "OTP"
}

This means:

• The payment is not complete yet
• The customer must perform an additional step
• You must collect the required input and submit it for authorization (if applicable)

Authorization Flow (High Level)

1. Initiate Direct Charge
2. Chapa responds with auth_type
3. Prompt customer for required input (PIN / OTP / USSD)
4. Submit authorization data (if required)
5. Payment completes or fails
6. Receive webhook and verify final status

Authorization Types

PIN Authorization

• Customer enters their mobile money PIN
• Common for wallet-based payments
• Requires secure input handling

OTP Authorization

• Customer receives an OTP via SMS or email
• OTP must be submitted before expiration
• Often time-bound (expires_at)

USSD Authorization

• Customer dials a USSD code on their phone
• No additional API call may be required
• Status updates arrive via webhook

Authorization via Webhook

When authorization is required, Chapa sends a webhook event:

Event: payment.auth_needed

{
  "webhook_type": "payment",
  "event": "payment.auth_needed",
  "status": "auth_needed",
  "mode": "live",
  "payment_type": "Direct charge",
  "currency": "ETB",
  "amount": "40000",
  "merchant_reference": "TXN123AUTH",
  "chapa_reference": "CHREF123",
  "auth_type": "PIN",
  "expires_at": "2025-11-07T13:00:00Z",
  "created_at": "2025-11-07T12:00:00Z",
  "updated_at": "2025-11-07T13:00:00Z"
}

Use this webhook to:

• Notify your frontend
• Prompt the customer
• Enforce authorization time limits

Submitting Authorization (Conceptual)

A typical authorization payload includes:

Example (Conceptual):

{
  "chapa_reference": "CHREF123",
  "auth_type": "OTP",
  "auth_value": "123456"
}

Handling Authorization Outcomes

Success

• Payment transitions to success
• Webhook: payment.success
• Verification confirms success

Failure

• Payment transitions to failed
• Webhook: payment.failed
• Reason provided (e.g. invalid PIN, OTP expired)

Timeout

• Payment transitions to incomplete
• Webhook: payment.incomplete

Best Practices

• Clearly inform customers why authentication is required
• Mask sensitive inputs (PIN / OTP)
• Enforce timeouts using expires_at
• Never log or store PINs or OTPs
• Use webhooks to finalize payment state
• Verify payment after authorization completes

Common Errors

Security Notes (Critical)

Next Steps

• Initiate Payment - Start a Direct Charge
• Verify Payments - Confirm payment status
• Webhooks - Handle payment events