Retrieve payment status

Retrieves how far a payment has got and what the buyer must do next, if anything. A payment is collected in the background, so poll this rather than reading the create response. Accepts either a secret key or the payment’s own client_secret, so the surface collecting the payment can poll it directly.

GET /payments/{payment_id}/status

JavaScript

JavaScript

import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const response = await client.payments.retrieveStatus('payment_id');

console.log(response.id);

200

{
  "id": "pay_xxxxxxxxxxxxxx",
  "last_payment_error": {
    "code": "processing_error",
    "decline_code": "insufficient_funds",
    "message": "Your card was declined."
  },
  "next_action": {
    "data": {
      "frame_max_width": 500,
      "url": "https://psp.example/3ds/challenge"
    },
    "render": [
      "inline"
    ],
    "type": "redirect"
  },
  "object": "payment_status",
  "processing_details": {
    "expected_by": "2026-01-01T12:00:00.000Z"
  },
  "return_url": "https://shinetime.example/checkout/done",
  "status": "requires_action"
}

Authorizations

Authorization · string · header · required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Path Parameters

payment_id · string · required

The unique identifier of the payment.

Response

200

application/json

Payment status retrieved

id · string · required

The payment this status describes, prefixed pay_.

Example:

"pay_xxxxxxxxxxxxxx"

last_payment_error · object | null · required

Details of the most recent failed attempt, or null when the payment has not failed.

Show child attributes

next_action · Redirect · object · required

What the buyer must do next while status is requires_action, otherwise null. type picks the shape and each variant carries only its own data, so switching on type gives you exactly that step's payload.

Redirect

Display instructions

Await confirmation

Show child attributes

object · string · required

Always payment_status.

Example:

"payment_status"

processing_details · object | null · required

Present while status is processing on a settlement rail, otherwise null.

Show child attributes

return_url · string | null · required

Where to send the buyer once the payment reaches a resting state, or null to leave them where they are. Editable until they return — see the return_url operation.

Example:

"https://shinetime.example/checkout/done"

status · enum<string> · required

How far the payment has got. requires_confirmation — nothing attempted yet, or the last attempt failed and can be retried. requires_action — the buyer has a step outstanding; see next_action. confirming — the buyer has done their part and the processor is deciding. processing — the money is moving; see processing_details. succeeded — collected. canceled — voided or written off.

Available options: requires_confirmation, requires_action, confirming, processing, succeeded, canceled

Example:

"requires_action"