Sign in
OpenAPI 3.1.02026-08-203914245.9 MB

4a1a4a5d2c72

Payments

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

Path parameters

payment_idstring required

The unique identifier of the payment.

Response

Payment status retrieved

idstring required

The payment this status describes, prefixed pay_.

objectstring required

Always payment_status.

return_urlstring nullable 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.

status'requires_confirmation' | 'requires_action' | 'confirming' | 'processing' | 'succeeded' | 'canceled' 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.

Example response

{
  "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"
}