---
title: "Retrieve payment status"
method: GET
path: "/payments/{payment_id}/status"
tags: ["Payments"]
---

# Retrieve payment status

`GET /payments/{payment_id}/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.

## Path parameters

- `payment_id` string, required

## Response `200`

Payment status retrieved

- PaymentStatus
  - `id` string, required — The payment this status describes, prefixed `pay_`.
  - `last_payment_error` PaymentLastPaymentError, required
    - `code` string, nullable, required — A machine-readable classification of the failure.
    - `decline_code` 'insufficient_funds' | 'lost_card' | 'stolen_card' | 'expired_card' | 'suspected_fraud' | 'invalid_card_number' | 'invalid_cvc' | 'invalid_cvc_or_expiration' | 'incorrect_pin' | 'authentication_required' | 'card_not_supported' | 'currency_not_supported' | 'duplicate_transaction' | 'generic_decline' | 'invalid_account' | 'invalid_amount' | 'processing_error' | 'restricted_card' | 'card_velocity_exceeded' | 'contact_issuer' | 'bank_declined' | 'regulatory_blocked' | 'transaction_not_permitted' | 'transaction_stopped' | 'card_type_not_supported' | 'issuer_not_found' | 'closed_account' | 'issuer_unavailable' | 'invalid_zip' | 'invalid_expiry_month' | 'invalid_expiry_year' | 'invalid_expiry' | 'invalid_transaction' | 'cannot_authorize' | 'pin_required' | 'pin_try_exceeded' | 'provider_declined' | 'high_risk' | 'test_mode_decline' | 'merchant_blacklist' | 'reenter_transaction' | 'invalid_pin' | 'pin_required_as' | 'withdrawal_count_limit_exceeded' | 'invalid_country' | 'issuer_error' | 'invalid_card_holder_name' | 'no_accounts' | 'transaction_cancelled' | 'three_d_secure_success' | 'three_d_secure_canceled' | 'three_d_secure_invalid_card_number' | 'three_d_secure_generic_error' | 'three_d_secure_timeout' | 'three_d_secure_failed' | 'three_d_secure_card_not_enrolled' | 'three_d_secure_fraud' | 'three_d_secure_too_many_attempts' | 'three_d_secure_rejected_by_bank' | 'three_d_secure_reported_lost_or_stolen' | 'blocked_by_cardholder' | 'test_mode_test_card' | 'try_again_later' | 'transaction_not_allowed' | 'bank_insufficient_funds' | 'bank_account_not_found' | 'bank_account_closed' | 'bank_account_frozen' | 'bank_invalid_routing_number' | 'bank_non_transaction_account' | 'bank_authorization_revoked' | 'bank_payment_stopped' | 'bank_not_authorized' | 'bank_account_holder_deceased' | 'bank_duplicate' | 'bank_amount_error' | 'bank_regulatory_blocked' | 'bank_details_invalid' | 'bank_processing_error' | 'bank_generic_decline' | 'sepa_invalid_iban' | 'sepa_no_mandate' | 'sepa_mandate_data_invalid' | 'sepa_disputed' | 'sepa_refused_by_customer' | 'sepa_generic_decline' | 'null', nullable, required — The reason the payment was declined.
    - `message` string, nullable, required — A human-readable explanation of the failure.
  - `next_action` PaymentNextAction, required
    - `data` object, required — The payload for this step's type: `url` for `redirect`, `kind` plus that kind's details for `display_instructions`, `expires_at` for `await_confirmation`.
    - `render` string[], required
    - `type` 'redirect' | 'display_instructions' | 'await_confirmation', required — What kind of step this is. `redirect` — send the buyer to `data.url`. `display_instructions` — show them `data`, such as a voucher code or bank transfer details. `await_confirmation` — nothing to show; they have done their part.
  - `object` string, required — Always `payment_status`.
  - `processing_details` PaymentProcessingDetails, required
    - `expected_by` string, nullable, required — When the payment is expected to settle, as an ISO 8601 timestamp.
  - `return_url` string, 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.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Resource not found

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/866821546d67/schema)