Skip to main content

​
Overview

Paystack is the payment processor used by the Telegram Subscription Manager to accept payments in Nigerian Naira (NGN). This guide covers account setup, API key configuration, and webhook integration.

​
Prerequisites

  • A registered business or personal account in Nigeria
  • Valid bank account for receiving payments
  • Phone number and email for verification

​
Create Paystack Account

1

Sign Up

  1. Go to Paystack
  2. Click “Sign Up” or “Get Started”
  3. Choose account type:
    • Personal: For individuals
    • Business: For registered businesses
  4. Fill in your details:
    • Full name
    • Email address
    • Phone number
    • Password
  5. Click “Create Account”
2

Verify Email

  1. Check your email for verification link
  2. Click the link to verify your email
  3. You’ll be redirected to the Paystack dashboard
3

Complete KYC (Know Your Customer)

To activate your account for live payments:
  1. Go to Settings → Account
  2. Complete the required information:
    • Business/Personal details
    • Bank account information (for receiving settlements)
    • Government-issued ID
    • Business registration documents (if applicable)
Test mode works immediately without KYC. Complete KYC only when ready for production.

​
Get API Keys

1

Navigate to API Settings

  1. Log in to your Paystack Dashboard
  2. Click Settings in the sidebar
  3. Select API Keys & Webhooks
2

Copy Secret Key

You’ll see two types of keys:
For Development:
  • Test Public Key: pk_test_... (not needed for this app)
  • Test Secret Key: sk_test_... (use this for testing)
Use test keys to:
  • Develop and test locally
  • Verify integration without real money
  • Use Paystack’s test cards
Test mode payments don’t require KYC completion.
Copy the Secret Key for the environment you want (test or live).
3

Add to Environment Variables

Add your secret key to .env.local:
.env.local
# For testing
PAYSTACK_SECRET_KEY=sk_test_your_test_secret_key_here

# For production (after KYC approval)
# PAYSTACK_SECRET_KEY=sk_live_your_live_secret_key_here
Never commit your secret key to Git! Keep .env.local in .gitignore.

​
Configure Payment Plans

The Telegram Subscription Manager supports multiple subscription plans defined in src/lib/config.ts:
src/lib/config.ts
export const PLANS = {
  basic: {
    name: 'Basic VIP',
    amountKobo: 500000,  // NGN 5,000
    durationDays: 7,
    hasCopierAccess: false
  },
  biweekly: {
    name: 'Bi-Weekly VIP',
    amountKobo: 1000000,  // NGN 10,000
    durationDays: 14,
    hasCopierAccess: false
  },
  monthly: {
    name: 'Monthly VIP',
    amountKobo: 1500000,  // NGN 15,000
    durationDays: 30,
    hasCopierAccess: false
  },
  premium: {
    name: 'Premium VIP + Copier',
    amountKobo: 2200000,  // NGN 22,000
    durationDays: 14,
    hasCopierAccess: true
  }
}
Kobo: Paystack uses kobo (smallest unit of Nigerian currency).
  • NGN 1.00 = 100 kobo
  • NGN 5,000 = 500,000 kobo

​
Update Bank Details

Users will see bank details for manual transfers. Update them in src/lib/config.ts:
src/lib/config.ts
export const BANK_DETAILS = {
  bankName: 'YOUR BANK NAME',
  accountNumber: '0123456789',
  accountName: 'Your Account Name'
}
Use your Paystack-provided account details if you want to use Paystack’s payment collection features.

​
Set Up Webhooks (Optional)

Webhooks allow Paystack to notify your app about payment events in real-time.
Webhooks are optional for this bot. The bot primarily uses the /verify_basic and /verify_premium commands which directly verify payments via the Paystack API.
If you want to enable webhooks for additional automation:
1

Deploy Your Application

Webhooks require a publicly accessible URL. Deploy to Vercel first:
2

Configure Webhook in Paystack

  1. Go to Settings → API Keys & Webhooks
  2. Scroll to Webhook URL
  3. Enter your webhook endpoint: 
    https://your-app.vercel.app/api/paystack/webhook
  4. Click “Save Changes”
3

Test Webhook

Paystack provides a webhook testing tool:
  1. In the webhook settings, click “Test Webhook”
  2. Select an event type (e.g., charge.success)
  3. Click “Send Test”
  4. Verify your endpoint returns a 200 status
Check Vercel logs to confirm webhook was received.

​
Webhook Events

The app listens for these Paystack events:
EventDescriptionAction
charge.successPayment completed successfullyVerify and process subscription
charge.failedPayment failedLog for monitoring
refund.processedRefund completedUpdate subscription status

​
Test Payments

Before going live, test the payment flow:

​
Test Cards

Paystack provides test cards for different scenarios:
Card Number: 4084084084084081
  • CVV: Any 3 digits
  • Expiry: Any future date
  • PIN: 0000
  • OTP: 123456
Use this to test successful subscriptions.

​
Testing Workflow

1

Make Test Payment

  1. Use Paystack’s test payment page or integrate with your frontend
  2. Use one of the test card numbers above
  3. Complete the payment flow
  4. Note the transaction reference (e.g., T123456789)
2

Verify via Bot

  1. Open your Telegram bot
  2. Send command: 
    /verify_basic T123456789
  3. Bot should verify the payment and grant access
3

Check Database

Verify subscription was created:
npx prisma studio
Look for the subscription in the Subscription table.
Test mode transactions appear in your Paystack dashboard but don’t involve real money.

​
Go Live

When ready to accept real payments:
1

Complete KYC

Ensure your Paystack account is fully verified:
  • Business/personal details submitted
  • Bank account verified
  • Identity documents approved
2

Get Live API Key

  1. Go to Settings → API Keys & Webhooks
  2. Copy your Live Secret Key (sk_live_...)
3

Update Environment Variables

In Vercel:
  1. Go to Project Settings → Environment Variables
  2. Update PAYSTACK_SECRET_KEY with your live key
  3. Redeploy your application
Locally (optional):
.env.local
PAYSTACK_SECRET_KEY=sk_live_your_live_secret_key_here
4

Test with Real Payment

Make a small real payment to verify:
  1. Use your own card for a small amount
  2. Verify payment via bot
  3. Check channel access works
  4. Verify settlement appears in Paystack dashboard
Before going live:
  • Test all subscription plans
  • Verify expiry cron job works
  • Test edge cases (wrong amounts, invalid references)
  • Ensure customer support contact is visible

​
Payment Verification Flow

Understanding how payments are verified:

​
Verification Checks

The bot performs these checks before granting access:
  1. ✅ Valid reference format: Basic validation
  2. ✅ Payment exists: Paystack API confirms transaction
  3. ✅ Payment successful: Status is “success”
  4. ✅ Correct amount: Matches the plan being verified
  5. ✅ Reference unused: Not redeemed before
  6. ✅ Not rate limited: User hasn’t failed too many times

​
Troubleshooting

Error: "Invalid key"Solutions:
  1. Verify you copied the Secret Key, not Public Key
  2. Check for extra spaces or quotes in environment variable
  3. Ensure using correct key for environment (test vs live)
  4. Verify key starts with sk_test_ or sk_live_
Test API key:
curl https://api.paystack.co/transaction \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
Common causes:
  1. Wrong reference format:
    • Should be alphanumeric
    • Check user didn’t add spaces
    • Reference is case-sensitive
  2. Payment not successful:
    • Check status in Paystack dashboard
    • User might have abandoned payment
    • Payment might have failed
  3. Amount mismatch:
    • User paid wrong amount
    • User used wrong command (e.g., paid NGN 22,000 but used /verify_basic)
  4. Reference already used:
    • Check database for existing subscription with that reference
    • User trying to reuse old payment
Troubleshooting:
  1. Verify webhook URL: 
    curl https://your-app.vercel.app/api/paystack/webhook
    Should return 200 status.
  2. Check Paystack webhook logs:
    • Go to Settings → API Keys & Webhooks
    • Scroll to Webhook Logs
    • Check delivery status and errors
  3. Test webhook manually: Use Paystack’s webhook testing tool in dashboard.
  4. Verify signature validation: Ensure webhook handler validates Paystack signature.
Check settlement schedule:
  • New accounts: T+7 days (7 days after transaction)
  • Established accounts: T+2 or T+1 days
Verify bank details:
  1. Go to Settings → Account
  2. Check bank account information
  3. Ensure account is verified
Check settlement history:
  • Go to Settlements in dashboard
  • View pending and completed settlements
  • Check for any holds or issues

​
Security Best Practices

Protect Your Secret Key:
  • Never commit to version control
  • Never share publicly or in screenshots
  • Regenerate if compromised
  • Use environment variables only
Monitor Transactions: Regularly check your Paystack dashboard for:
  • Failed payments
  • Unusual transaction patterns
  • Chargebacks or disputes
  • Settlement status

​
Paystack Fees

Paystack charges per transaction:
Transaction AmountFee
Local cards1.5% capped at NGN 2,000
International cards3.9%
Fees are automatically deducted from settlements. You receive the net amount.

​
Next Steps

Database Setup

Configure MongoDB and Prisma

Deploy to Vercel

Deploy your complete application

Build docs developers (and LLMs) love

Get started for freeTalk to us