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`	Lowercase currency code: `usd` or `cad`
`customerEmail`	Customer's email (if provided)
`description`	Payment description, or `null` if none was provided
`metadata`	Your custom metadata keys, or `null` if there are none. Keys starting with an underscore (`_`) are reserved for internal use and are never returned, so don't use them for your own data. A `description` key is not included here: if its value is a string, it is returned as the top-level `description` field instead (a top-level description you sent takes precedence); otherwise it is dropped.
`stripeSessionId`	Stripe Checkout Session ID
`stripePaymentIntentId`	Stripe Payment Intent ID (after payment)
`createdAt`	When payment was created
`completedAt`	When the payment reached a final status, such as succeeded, failed, cancelled or expired (`null` while pending or processing)

Payment Statuses

Status	Description
pending	Payment record created, but the checkout link has not been issued yet. You won't normally see this, because Create Payment only returns once the checkout link exists.
processing	Checkout link created and waiting for the customer to pay. This is the status right after Create Payment returns; it does not mean the customer has opened 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"