Auto-Verify Payment

Overview

This endpoint performs complete payment verification with Paystack and automatically activates the user’s subscription. It verifies the transaction status, validates the payment amount and channel, creates an invite link, saves the subscription to the database, and sends the invite link to the user via Telegram.

This endpoint is called from the payment success page to provide immediate subscription activation without waiting for the Paystack webhook.

Authentication

No authentication required. This is a public endpoint called from the payment success page.

Request

Headers

Content-Type

string

required

Must be application/json

Body Parameters

reference

string

required

The Paystack transaction reference ID to verify

Response

Success Response (200)

success

boolean

true if verification and activation succeeded

message

string

Success message: “Payment verified and invite link sent”

telegramId

string

The Telegram user ID of the subscriber

planType

string

The activated subscription plan type

Error Responses

success

boolean

false when verification fails

error

string

Detailed error message describing the failure reason

Status Codes

200 - Request processed (check success field for actual result)
400 - Missing reference parameter

Validation Rules

The endpoint performs the following validations:

1. Reference Validation

reference

string

required

Must be provided and cannot be empty

2. Duplicate Transaction Check

Verifies the reference hasn’t been used before by checking the database for existing subscriptions with the same paystackRef. Error: “This transaction has already been redeemed”

3. Paystack Verification

Verifies the transaction with Paystack API:

Transaction must exist
Transaction status must be “success”

Errors:

“Payment verification failed”
“Payment was not completed successfully”

4. Payment Channel Validation

Ensures payment was made through an allowed channel:

bank_transfer (preferred)
card (also accepted)

Error: “Invalid payment method”

5. Telegram ID Validation

Extract Telegram ID from transaction metadata (required for subscription activation). Error: “Payment not linked to Telegram account”

6. Amount Validation

Verifies the paid amount matches the plan price:

Tolerance: ±NGN 1,500 (to account for Paystack fees)
Amount must be at least the expected plan amount

Error: “Payment amount (NGN X) is less than required (NGN Y)“

Subscription Activation Process

Unban Previously Removed Users

If the user was previously removed for non-payment, unban them from the Telegram channel using unbanChatMember().

Create Invite Link

Generate a one-time Telegram invite link valid for 24 hours using createInviteLink().Error: “Failed to create invite link”

Calculate Expiry Date

Compute subscription expiry based on plan duration:

Basic: 7 days
Bi-weekly: 14 days
Monthly: 30 days
Premium: 14 days
Promo: 7 days

Save to Database

Create subscription record with:

telegramUserId
telegramUsername
paystackRef
customerEmail
amountKobo
planType
hasCopierAccess
startedAt (current timestamp)
expiresAt (calculated expiry)
inviteLinkUsed

Error: “Failed to save subscription”

Send Telegram Message

Send invite link and subscription details to the user via Telegram bot.For Premium plans with copier access, includes MT5 setup instructions.

Set Conversation State (Premium Only)

For Premium plans, initialize MT5 setup conversation state to account_number step.

Examples

curl -X POST https://your-domain.com/api/payment/auto-verify \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ref_abc123xyz789"
  }'

Success Response Example

{
  "success": true,
  "message": "Payment verified and invite link sent",
  "telegramId": "123456789",
  "planType": "premium"
}

Error Response Examples

Show 400 - Missing Reference

{
  "success": false,
  "error": "Reference is required"
}

Show Already Redeemed

{
  "success": false,
  "error": "This transaction has already been redeemed"
}

Show Verification Failed

{
  "success": false,
  "error": "Payment verification failed"
}

Show Payment Not Completed

{
  "success": false,
  "error": "Payment was not completed successfully"
}

Show Invalid Payment Method

{
  "success": false,
  "error": "Invalid payment method"
}

Show No Telegram ID

{
  "success": false,
  "error": "Payment not linked to Telegram account"
}

Show Amount Mismatch

{
  "success": false,
  "error": "Payment amount (NGN 4,800) is less than required (NGN 5,000)."
}

Show Failed to Create Invite Link

{
  "success": false,
  "error": "Failed to create invite link"
}

Show Failed to Save Subscription

{
  "success": false,
  "error": "Failed to save subscription"
}

Show Auto-Verification Failed

{
  "success": false,
  "error": "Auto-verification failed"
}

Telegram Message Content

Basic Plans Message

✅ Payment Verified Successfully!

💎 Plan: Basic VIP
💰 Amount: NGN 5,000
📅 Access expires: Mar 10, 2026

Here is your one-time invite link (valid for 24 hours):
👉 https://t.me/+abc123xyz

Click the link to join the channel. The link can only be used once.

Type /status anytime to check your subscription.

Premium Plan Message (with MT5 Copier)

Show View Full Premium Message

Includes all basic plan content plus:

━━━━━━━━━━━━━━━━━━━

🤖 MT5 AUTO COPIER ACTIVATED!

━━━━━━━━━━━━━━━━━━━

⚠️ CRITICAL REQUIREMENTS:

1. YOUR ACCOUNT MUST BE A CENT ACCOUNT!
❌ Standard Account - WILL NOT WORK
✅ Cent Account - REQUIRED

2. SCALING: DISABLED (No Scaling)
💡 Copy trades exactly as master opens them

3. MAGIC NUMBER: 123456
🔢 Set this in your MT5 EA settings

4. REGION: LONDON
🌍 Your copier will use London region

━━━━━━━━━━━━━━━━━━━

Copy Settings Explained Simply:

📊 Multiplier (1.0x):
"Default setting - Copy same size as master"

Examples in baby language:
• 1.0x = Master opens 0.01 → You open 0.01 ✅
• 2.0x = Master opens 0.01 → You open 0.02 📈
• 3.0x = Master opens 0.01 → You open 0.03 🚀

"Higher multiplier = Bigger trades = More profit BUT more risk!"

📏 Max Lot (0.2):
"Biggest trade we'll copy is 0.2 lots"

🔢 Max Positions (10):
"Maximum 10 trades at the same time"

━━━━━━━━━━━━━━━━━━━

🎁 DON'T HAVE A HEADWAY ACCOUNT?

Create one here and get $100 BONUS!
👉 https://headway.partners/user/signup?hwp=82067c

━━━━━━━━━━━━━━━━━━━

To set up your copier, type:
/mt5setup

Or skip for now - you have access for your full 14 days!

Implementation Notes

Required Environment Variables:

PAYSTACK_SECRET_KEY - For Paystack API verification
TELEGRAM_BOT_TOKEN - For sending messages and creating invite links
Database connection (Prisma) must be configured

Metadata Extraction Logic

The endpoint extracts Telegram ID from transaction metadata in two ways:

Direct metadata fields: metadata.telegram_id
Custom fields array: Searches metadata.custom_fields for variable_name === 'telegram_id'

This dual approach ensures compatibility with different payment link creation methods.

Plan Type Detection

Similarly extracts plan type from:

metadata.plan_type
Custom field with variable_name === 'plan_type'
Defaults to 'basic' if not found

Amount Tolerance

Paystack adds transaction fees, so the endpoint allows up to NGN 1,500 (150,000 kobo) variance:

₦5,000 plan: ~₦100-200 in fees
₦22,000 plan: ~₦1,000 in fees

Premium Plan Features

For plans with hasCopierAccess: true:

Extended message with MT5 setup instructions
Conversation state initialized to account_number step
User can type /mt5setup to configure their copier

Database Schema

The subscription record created includes:

{
  telegramUserId: string       // Telegram user ID
  telegramUsername?: string    // Telegram username
  telegramName: string         // Display name from Paystack
  paystackRef: string          // Transaction reference (unique)
  customerEmail?: string       // Customer email
  amountKobo: number          // Amount paid in kobo
  planType: PlanType          // Plan type enum
  hasCopierAccess: boolean    // MT5 copier access flag
  startedAt: Date             // Subscription start
  expiresAt: Date             // Subscription expiry
  inviteLinkUsed: string      // Invite link generated
}

Error Handling

All errors are logged to console with context:

console.log('Auto-verifying payment:', reference)
console.log('Auto-verifying for telegram_id:', telegramId, 'plan:', planType)
console.error('Verification failed:', verification.error)
console.error('Error saving subscription:', error)
console.error('Error in auto-verify:', error)

This enables debugging payment issues through server logs.

Webhooks

Payment

Admin

Overview

Authentication

Request

Headers

Body Parameters

Response

Success Response (200)

Error Responses

Status Codes

Validation Rules

1. Reference Validation

2. Duplicate Transaction Check

3. Paystack Verification

4. Payment Channel Validation

5. Telegram ID Validation

6. Amount Validation

Subscription Activation Process

Examples

Success Response Example

Error Response Examples

Telegram Message Content

Basic Plans Message

Premium Plan Message (with MT5 Copier)

Implementation Notes

Metadata Extraction Logic

Plan Type Detection

Amount Tolerance

Premium Plan Features

Database Schema

Error Handling

Build docs developers (and LLMs) love

Webhooks

Payment

Admin

​Overview

​Authentication

​Request

​Headers

​Body Parameters

​Response

​Success Response (200)

​Error Responses

​Status Codes

​Validation Rules

​1. Reference Validation

​2. Duplicate Transaction Check

​3. Paystack Verification

​4. Payment Channel Validation

​5. Telegram ID Validation

​6. Amount Validation

​Subscription Activation Process

​Examples

​Success Response Example

​Error Response Examples

​Telegram Message Content

​Basic Plans Message

​Premium Plan Message (with MT5 Copier)

​Implementation Notes

​Metadata Extraction Logic

​Plan Type Detection

​Amount Tolerance

​Premium Plan Features

​Database Schema

​Error Handling

Build docs developers (and LLMs) love

Overview

Authentication

Request

Headers

Body Parameters

Response

Success Response (200)

Error Responses

Status Codes

Validation Rules

1. Reference Validation

2. Duplicate Transaction Check

3. Paystack Verification

4. Payment Channel Validation

5. Telegram ID Validation

6. Amount Validation

Subscription Activation Process

Examples

Success Response Example

Error Response Examples

Telegram Message Content

Basic Plans Message

Premium Plan Message (with MT5 Copier)

Implementation Notes

Metadata Extraction Logic

Plan Type Detection

Amount Tolerance

Premium Plan Features

Database Schema

Error Handling