Get Payment Status

Check the current status of a payment using its transaction ID.

GET/api/v1/payments/:id

Response

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "succeeded",
    "amount": 5000,
    "currency": "usd",
    "customerEmail": "customer@example.com",
    "description": "Order #12345",
    "metadata": {
      "orderId": "12345"
    },
    "stripeSessionId": "cs_live_a1b2c3d4...",
    "stripePaymentIntentId": "pi_3ABC123...",
    "createdAt": "2025-01-01T12:00:00.000Z",
    "completedAt": "2025-01-01T12:05:00.000Z"
  }
}

Response Fields

Field	Description
`id`	UltraPay transaction ID
`status`	Current payment status (see below)
`amount`	Amount in cents
`currency`	3-letter currency code
`customerEmail`	Customer's email (if provided)
`description`	Payment description (if provided)
`metadata`	Your custom metadata (if provided)
`stripeSessionId`	Stripe Checkout Session ID
`stripePaymentIntentId`	Stripe Payment Intent ID (after payment)
`createdAt`	When payment was created
`completedAt`	When payment completed (null if pending)

Payment Statuses

Status	Description
pending	Payment created, waiting for customer
processing	Customer is on the checkout page
succeeded	✅ Payment completed successfully
failed	Payment failed (card declined, etc.)
expired	Checkout session expired (30 min timeout)
cancelled	Payment cancelled by you or customer
refunded	Payment was fully refunded
partially_refunded	Payment was partially refunded
disputed	Customer filed a chargeback
dispute_won	Dispute resolved in your favor
dispute_lost	Dispute resolved in customer's favor

Note: Only succeeded payments should trigger order fulfillment.

cURL Example

bash

curl -X GET https://pay.ultrapay.cc/api/v1/payments/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Public-Key: upp_your_public_key" \
  -H "X-Secret-Key: ups_your_secret_key"