Skip to main content
POST
/
api
/
payment
/
callback
Payment Callback
curl --request POST \
  --url https://api.example.com/api/payment/callback \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "reference": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "error": "<string>"
}

​
Overview

This endpoint receives payment callbacks from the success page after a user completes payment. It serves as a notification endpoint only - actual payment verification and subscription activation happens via the Paystack webhook or auto-verify endpoint.
This is a notification-only endpoint. The actual verification logic is handled by:
  • Paystack webhook for automated verification
  • /api/payment/auto-verify endpoint for manual verification

​
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 returned from the payment link creation

​
Response

​
Success Response (200)

​
success
boolean
Always true on success
​
message
string
Confirmation message: “Payment callback received. Check your Telegram for invite link.”

​
Error Responses

​
error
string
Error message describing what went wrong

​
Status Codes

  • 200 - Callback received successfully
  • 400 - Missing reference parameter
  • 500 - Internal server error

​
Examples

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

​
Success Response Example

{
  "success": true,
  "message": "Payment callback received. Check your Telegram for invite link."
}

​
Error Response Examples

​
Workflow Context

This endpoint fits into the payment flow as follows:
  1. User initiates payment via /api/payment/link
  2. User completes payment on Paystack checkout page
  3. Paystack redirects user to success page
  4. Success page calls this endpoint (notification only)
  5. Success page also calls /api/payment/auto-verify for immediate verification
  6. Alternatively, Paystack webhook handles verification asynchronously
Do not rely on this endpoint for payment verification. It only confirms that the user reached the success page, not that payment was actually completed or verified.

​
Implementation Notes

  • This endpoint does not verify the payment status with Paystack
  • No database operations are performed
  • The endpoint simply acknowledges receipt of the callback
  • The response message instructs users to check Telegram, assuming auto-verify or webhook will handle the actual subscription activation
  • Error handling is minimal since this is a fire-and-forget notification

Build docs developers (and LLMs) love

Get started for freeTalk to us