POST/api/v1/payment/authorize

Direct Payment Authorization

Authorize a previously initiated direct payment request using a transaction reference and OTP (One-Time Password).

When to Use

Use this endpoint only if the financial institution requires OTP-basedauthentication for processing payments.

Authentication

Requires the following headers:

app-id: Your application identifier (from Account Management → Generate API Key → APP id)

api-key: Your secret API key (from Account Management → Generate API Key → API Keys)

Processing Logic

Validates Reference and OTP: Verifies the provided reference and OTP are valid
Confirms with Bank: Confirms the transaction with the bank/financial institution
Updates Transaction Status: Sets status to PROCESSED or FAILED
Sends Webhook: Sends callback notification if a webhook URL is configured (portal setting or callback_url from original request)

Request Parameters

Required Fields

referencestringRequired

Beqelal-generated transaction ID from the payment request step

otpnumberRequired

6-digit OTP sent to customer by the financial institution

Webhook Configuration

If no webhook URL is configured (neither in portal nor in original request), no webhook will be sent
Override: If callback_url was provided in the original payment request, it overrides the portal-configured webhook URL
Default: Configure your webhook URL and secret in the Merchant Portal (Integration → Webhooks)

Response

Returns transaction details, including:

Amount, fees, total amount
Bank and merchant details
Status (e.g., PROCESSED or FAILED)
Transaction ID

Code Examples

Request

curl -X POST "{base_url}/api/v1/payment/authorize" \
  -H "Content-Type: application/json" \
  -H "app-id: YOUR_APP_ID" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
  "reference": "2CU210EXT4",
  "otp": 657894
}'

Response Examples

Successful response (200)

200 - OK

Example Value

{
  "id": "4EA310DX85",
  "bank_name": "Kacha DFS",
  "merchant": "Hulu Sport Betting company",
  "merchant_phone": "251989840055",
  "phone": "251989847777",
  "account_no": "251989847777",
  "amount": 100,
  "fee": 0,
  "total_amount": 100,
  "process": "Direct Payment(API)",
  "description": "Direct Payment(AP)",
  "updated_at": "2025-05-10T21:40:20.700053",
  "status": "PROCESSED",
  "status_code": 200,
  "message": "SUCCESS",
  "detail": "Operation Completed Successfully"
}

Transaction does not exist (400)

400 - Transaction not found

Example Value

{
  "error": {
    "status": "FAILED",
    "status_code": "442",
    "message": "TRANSACTION_NOT_FOUND",
    "detail": "Transaction does not exist with this reference number."
  }
}

Invalid OTP (400)

400 - Invalid OTP

Example Value

{
  "error": {
    "status": "FAILED",
    "status_code": "450",
    "message": "INVALID_OTP",
    "detail": "Invalid OTP"
  }
}

Unauthorized IP Access (479)

479 - Unauthorized IP

Example Value

{
  "error": {
    "status": "FAILED",
    "status_code": "479",
    "message": "UNAUTHORIZED_IP_ACCESS",
    "detail": "Unauthorized IP address access."
  }
}

Important Notes

OTP-Only Flow: This endpoint is only applicable for OTP-authenticated flows
Valid OTP: OTP must be a valid 6-digit code
Reference Required: Reference is required and must be valid (from the payment request step)

Direct Payment

Banks List