Skip to main content
POST
/
api
/
payment
/
link
Create Payment Link
curl --request POST \
  --url https://api.example.com/api/payment/link \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "telegramId": "<string>",
  "planType": "<string>",
  "telegramUsername": "<string>",
  "email": "<string>"
}
'
{
  "success": true,
  "authorizationUrl": "<string>",
  "reference": "<string>",
  "plan": "<string>",
  "amount": 123,
  "error": "<string>",
  "details": "<string>",
  "product": "<string>",
  "plan_type": "<string>",
  "telegram_id": "<string>",
  "telegram_username": "<string>",
  "plan_name": "<string>",
  "customer_email": "<string>",
  "custom_fields": [
    {}
  ]
}

​
Overview

This endpoint initializes a Paystack payment transaction and returns an authorization URL for the user to complete payment via bank transfer. The endpoint creates a payment link tied to a specific Telegram user and subscription plan.

​
Authentication

No authentication required. This is a public endpoint called from the Telegram bot.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
telegramId
string
required
The Telegram user ID of the subscriber
​
planType
string
required
The subscription plan type. Must be one of:
  • basic - Basic VIP (NGN 5,000, 7 days)
  • biweekly - Bi-Weekly VIP (NGN 10,000, 14 days)
  • monthly - Monthly VIP (NGN 15,000, 30 days)
  • premium - Premium VIP + Copier (NGN 22,000, 14 days)
  • promo - Promo VIP (NGN 3,000, 7 days)
​
telegramUsername
string
The Telegram username (optional)
​
email
string
Customer email address. If not provided, defaults to customer_{telegramId}@example.com

​
Response

​
Success Response (200)

​
success
boolean
Always true on success
​
authorizationUrl
string
The Paystack payment URL where the user should be redirected
​
reference
string
Unique Paystack transaction reference ID
​
plan
string
The selected plan type
​
amount
number
Transaction amount in kobo (Nigerian currency: 100 kobo = 1 Naira)

​
Error Responses

​
error
string
Error message describing what went wrong
​
details
string
Additional error details from Paystack (only included in 500 errors)

​
Status Codes

  • 200 - Payment link created successfully
  • 400 - Missing required fields (telegramId or planType)
  • 500 - Failed to create payment link or internal server error

​
Payment Configuration

The payment link is configured with the following Paystack settings:
  • Channel: Bank transfer only (channels: ['bank_transfer'])
  • Currency: Nigerian Naira (NGN)
  • Metadata: Includes product info, plan details, Telegram ID, and custom fields

​
Examples

curl -X POST https://your-domain.com/api/payment/link \
  -H "Content-Type: application/json" \
  -d '{
    "telegramId": "123456789",
    "telegramUsername": "johndoe",
    "planType": "premium",
    "email": "[email protected]"
  }'

​
Success Response Example

{
  "success": true,
  "authorizationUrl": "https://checkout.paystack.com/abc123xyz",
  "reference": "ref_abc123xyz789",
  "plan": "premium",
  "amount": 2200000
}

​
Error Response Examples

​
Metadata Stored in Transaction

The following metadata is attached to the Paystack transaction:
​
product
string
Always set to telegram_bot_subscription
​
plan_type
string
The selected plan type
​
telegram_id
string
Telegram user ID
​
telegram_username
string
Telegram username or ‘unknown’
​
plan_name
string
Capitalized plan name (e.g., “Premium VIP + Copier”)
​
customer_email
string
Customer email address
​
custom_fields
array
Array of custom fields with display names for Paystack dashboard:
  • Plan Type
  • Telegram ID
  • Customer Email

​
Implementation Notes

This endpoint requires the PAYSTACK_SECRET_KEY environment variable to be configured. The transaction will fail if the API key is invalid or missing.
  • The amount is automatically calculated from the plan type using the PLANS configuration
  • Payment channel is restricted to bank transfer only
  • The transaction reference from Paystack should be stored for later verification
  • Users are redirected to the authorization URL to complete payment

Build docs developers (and LLMs) love

Get started for freeTalk to us