POST/api/v1/create/payment-link

Create Payment Link

Initiates a payment link for customer 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)

Parameters

Required Fields

phonestringRequired

Customer's phone number (min 9, max 13 characters)

amountnumberRequired

Transaction amount in ETB (min 1, max 1,000,000)

expires_atstringRequired

Expiration date and time (must be in the future, format: YYYY-MM-DDTHH:MM:SS)

callback_urlstring (url)Required

Webhook URL for payment notifications (must be a valid URL)

trace_numberstringRequired

Unique merchant reference for tracking (max 100 characters, must be globally unique)

Optional Fields

item_namestringOptional

Description of the product/service being purchased

quantitystringOptional

Quantity of items being purchased

reasonstringOptional

Reason or note for the payment

Response

Returns JSON containing:

Payment reference ID
Shareable payment link URL
Initial transaction status

Key Features

Shareable Link: Unlike checkout, payment links can be shared through any channel
Longer Validity: Payment links remain active until paid or manually deactivated
Multiple Use Cases: Perfect for invoicing, bill payments, or sending payment requests

Code Examples

Request

curl -X POST "{base_url}/api/v1/create/payment-link" \
  -H "Content-Type: application/json" \
  -H "app-id: YOUR_APP_ID" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
  "phone": "251911000000",
  "amount": 1000,
  "expires_at": "2026-12-24T12:10:00",
  "callback_url": "https://www.example.et/v1/",
  "trace_number": "45270040124001120400807008RU837456",
  "item_name": "banana",
  "quantity": "2 Klo",
  "reason": "tuty"
}'

Response Examples

Success (200)

200 - OK

Example Value

{
  "id": "4FR010DKRB",
  "phone": "251911000000",
  "amount": 1000,
  "item_name": "banana",
  "quantity": "2 Klo",
  "expires_at": "2026-12-24T12:10:00",
  "reason": "tuty",
  "status": "PROCESSED",
  "status_code": 200,
  "trace_number": "45270040124001120400807008RU837456",
  "payment_link": "https://checkout.beqelal.net/#/payment/link/867c7ff9-b425-4693-baf6-857f4aeb8e46"
}

Unauthorized IP Access (479)

479 - Unauthorized IP

Request from IP not whitelisted in Merchant Portal

Example Value

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

Redirect User to Payment Link

Checkout

Direct Payment