Direct Payments

Direct Payment Integration Guide

The Direct Payment API is designed for businesses that require full control over the payment experience and prefer to initiate transactions directly from their own applications—without redirecting users to a hosted checkout page.

This endpoint enables you to programmatically initiate payment transactions using a variety of supported payment methods, including Telebirr USSD and CBEBirr USSD. It is ideal for platforms that need seamless, embedded payment flows within their own interface.

By integrating this API, businesses can offer a streamlined and fully branded payment experience while maintaining the flexibility to manage transaction logic end-to-end.

Base URL

https://api.wagapay.net/api/v1/direct

Authentication

All API requests must include your API key in the request headers.

apiKey: your api key goes here

Initiate Direct Payment

Endpoint: POST /payment/v1/direct?payment_option={payment_option} Initiates a direct payment transaction using the specified payment method.

Payment Options

  • telebirr_ussd: Process payment using Telebirr USSD
  • cbebirr_ussd: Process payment using CBEBirr USSD

Headers:

NameRequiredTypeDescription
apiKeyYesstringYour unique API key for authentication

Query Parameters

NameRequiredTypeDescription
payment_optionYesstringThe payment method to be used (telebirr_ussd or cbebirr_ussd)

Request Body

NameRequiredTypeDescription
amountYesstringThe payment amount
currencyYesstringThe currency code (e.g., ETB).
order_numberYesstringYour unique order reference number
phoneYesstringCustomer's phone number

Example Request

{
  "amount": "100.00",
  "currency": "ETB",
  "order_number": "ORD123456789",
  "phone": "+251912345678"
}

Responses

Success Response

201 Created

Order registration successful.

{
  "message": "Transaction initiated successfully",
  "payment_status": "PENDING"
}
✅

Direct Payment Successful: Your payment order has been successfully registered.

Error Responses

400 Bad Request

The request could not be processed due to invalid input.

{
  "code": 400,
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "amount",
      "issue": "amount is required"
    }
  ]
}
⚠️

Bad Request: It seems like there was an issue with your request. Please check the input data and ensure all required fields are provided correctly.

401 Unauthorized

Authentication failed. Ensure the API key is correct.

{
  "code": 401,
  "message": "Invalid or missing API key"
}
❌

Unauthorized: Your API key is invalid or missing. Please provide a valid API key in the request header.

500 Internal Server Error

Server Error: An error occurred on the server side.

{
  "code": 500,
  "message": "Failed to process payment"
}
💥

Internal Server Error: We encountered an unexpected error on our side. Please try again later or contact support if the problem persists.

Key Notes:

  • Authentication: Make sure to include your API key in all requests.
  • Payment Options: Currently, the available payment options are telebirr_ussd and cbebirr_ussd.
  • Error Handling: The error responses will help you understand what went wrong with the request, such as missing parameters or invalid API keys.
Error CodesSecurity guide