Direct Payments

Direct Payment Integration Guide

The Direct Payment API allows you to initiate payment transactions directly from your application. This endpoint enables you to process payments using various payment methods including Telebirr USSD and CBEBirr USSD.

Base URL

https://api.wagapay.net/payment/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

    (more payment options to be added)

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 CodesWaga Webhook