Get Payment Status

Retrieve the status and details of a payment by Stripe payment intent ID

GET /api/payments/status/:paymentIntentId

cURL

curl -X GET https://api.vaniykempire.com/api/payments/status/pi_3MtwBwLkdIwHu7ix28a3tqPa \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

200 Success - Completed

{
  "purchase": {
    "_id": "65f1a2b3c4d5e6f7g8h9i0j1",
    "user": "507f1f77bcf86cd799439011",
    "content": {
      "_id": "507f191e810c19729de860ea",
      "title": "Advanced React Patterns",
      "description": "Learn advanced React patterns and best practices",
      "type": "course",
      "thumbnailUrl": "https://cdn.vaniykempire.com/thumbnails/react-course.jpg"
    },
    "amount": 29.99,
    "stripePaymentIntentId": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
    "status": "completed",
    "purchasedAt": "2024-03-15T10:30:00.000Z"
  }
}

Retrieves the purchase record and status for a specific Stripe payment intent. This endpoint is used to check whether a payment has been completed, is still pending, has failed, or has been refunded.

Authentication

Requires authentication. Users can only view their own payment status.

Path Parameters

paymentIntentId · string · required

The Stripe payment intent ID (starts with pi_). This is returned when creating a payment intent or can be obtained from Stripe webhooks.

Response

purchase · object

The purchase record with populated content details

Show purchase properties

_id · string

MongoDB ObjectId of the purchase record

user · string

MongoDB ObjectId of the user who made the purchase

content · object

Populated content details

Show content properties

_id · string

Content MongoDB ObjectId

title · string

Content title

description · string

Content description

type · string

Content type (e.g., “video”, “article”, “course”)

thumbnailUrl · string

URL to content thumbnail image

amount · number

Purchase amount in USD

stripePaymentIntentId · string

Stripe payment intent ID

status · string

Payment status: pending, completed, failed, or refunded

purchasedAt · string

ISO 8601 timestamp of when the purchase record was created

Purchase Status Values

Status	Description
pending	Payment intent created, waiting for payment completion
completed	Payment successfully processed by Stripe
failed	Payment failed (card declined, insufficient funds, etc.)
refunded	Payment was refunded by an administrator

cURL

curl -X GET https://api.vaniykempire.com/api/payments/status/pi_3MtwBwLkdIwHu7ix28a3tqPa \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

200 Success - Completed

{
  "purchase": {
    "_id": "65f1a2b3c4d5e6f7g8h9i0j1",
    "user": "507f1f77bcf86cd799439011",
    "content": {
      "_id": "507f191e810c19729de860ea",
      "title": "Advanced React Patterns",
      "description": "Learn advanced React patterns and best practices",
      "type": "course",
      "thumbnailUrl": "https://cdn.vaniykempire.com/thumbnails/react-course.jpg"
    },
    "amount": 29.99,
    "stripePaymentIntentId": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
    "status": "completed",
    "purchasedAt": "2024-03-15T10:30:00.000Z"
  }
}

Error Codes

Status Code	Description
200	Payment status retrieved successfully
401	Not authenticated
404	Payment intent not found or doesn’t belong to user
500	Server error

Security

• Users can only view payment status for their own purchases
• The query filters by both paymentIntentId and authenticated userId
• Payment intents from other users will return 404

Use Cases

• Poll this endpoint after payment to check if webhook processed successfully
• Display payment history to users
• Verify purchase before granting content access
• Show refund status to users

Related Endpoints

• Create Payment Intent - Start a new payment
• Webhook - How payment status gets updated
• List Payments - Admin endpoint to view all payments

Implementation Notes

• Content is populated with title, description, type, and thumbnailUrl fields
• User field is not populated in the response (only the ObjectId is returned)
• Source: src/controllers/paymentController.js:133-151