> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 결제 거절 및 갱신 실패 처리

> 각 거절 코드의 의미, Whop이 실패한 결제를 재시도하고 구독을 연체로 표시하는 방식, 고객이 카드를 업데이트하고 재시도하도록 돕는 방법을 알아보세요.

결제 거절의 원인, Whop이 이를 복구하기 위해 하는 일, 그리고 판매자나 고객이 거절된 결제를 해결하는 방법을 알아보세요.

## 구체적인 거절 사유 및 메시지

결제 대행사가 결제를 거절하면 다음과 같은 특정 거절 코드 중 하나를 받을 수 있습니다. 각 코드의 의미와 해결 방법은 다음과 같습니다.

| 거절 사유 | 설명 |
| - | - |
| `insufficient_funds` | 카드 잔액이 부족하여 구매를 완료할 수 없습니다. 다른 결제 수단을 사용하거나 계좌에 잔액이 충분한지 확인하세요. |
| `lost_card` | 카드 소지자가 카드를 분실 신고하여 카드 발급사가 결제를 거절했습니다. 다른 카드로 구매를 완료하세요. |
| `stolen_card` | 카드 소지자가 카드를 도난 신고하여 카드 발급사가 결제를 거절했습니다. 다른 카드로 구매를 완료하세요. |
| `expired_card` | 카드가 만료되었습니다. 만료일을 확인하고 다시 시도하거나 다른 카드를 사용하세요. |
| `suspected_fraud` | 보안 검사로 인해 결제가 차단되었습니다. 자세한 내용은 은행에 문의하거나 다른 결제 수단을 시도하세요. |
| `invalid_card_number` | 카드 번호가 올바르지 않습니다. 카드의 16자리 번호를 다시 확인하고 다시 시도하세요. |
| `invalid_cvc` | 카드 인증 코드(<abbr title="카드 인증 코드">CVC</abbr>)가 올바르지 않습니다. 카드 뒷면(Amex는 앞면)의 3자리 또는 4자리 코드를 확인하고 다시 시도하세요. |
| `invalid_cvc_or_expiration` | 카드 인증 코드(<abbr title="카드 인증 코드">CVC</abbr>) 또는 만료일이 올바르지 않습니다. 3자리 또는 4자리 보안 코드와 <abbr title="월/연도">MM/YY</abbr> 형식의 만료일을 모두 다시 확인하세요. |
| `incorrect_pin` | 입력한 개인 식별 번호(<abbr title="개인 식별 번호">PIN</abbr>)가 올바르지 않습니다. 올바른 번호로 다시 시도하세요. 이 거절은 카드 리더기로 결제한 경우에만 적용됩니다. |
| `authentication_required` | 이 결제에는 추가 인증이 필요합니다. 은행이 거래를 확인하기 위해 웹사이트를 열거나 문자 메시지를 보낼 수 있습니다. 계속하려면 인증을 완료하세요. |
| `card_not_supported` | 이 카드는 이 유형의 구매를 지원하지 않습니다. 다른 신용카드 또는 체크카드를 사용해 보세요. |
| `currency_not_supported` | 카드가 이 통화의 결제를 지원하지 않습니다. 다른 카드를 사용하거나 해외 거래에 대해 은행에 문의하세요. |
| `duplicate_transaction` | 동일한 금액과 카드로 방금 거래가 처리되었습니다. 이메일에서 확인 메일을 확인하세요. 받지 못했다면 몇 분 기다린 후 다시 시도하세요. |
| `generic_decline` | 카드 발급사가 결제를 거절했습니다. 다음을 시도해 보세요: 1) 다른 카드 사용, 2) 은행에 문의, 3) 청구 정보가 올바른지 확인. |
| `invalid_account` | 이 카드 또는 연결된 계좌가 유효하지 않습니다. 다른 카드를 사용하거나 은행에 도움을 요청하세요. |
| `invalid_amount` | 결제 금액이 카드 한도를 초과합니다. 더 적은 금액으로 시도하거나 다른 결제 수단을 사용하세요. |
| `processing_error` | 일시적인 문제로 결제 처리가 중단되었습니다. 잠시 기다린 후 다시 시도하거나 다른 카드를 사용하세요. |
| `restricted_card` | 은행이 이 카드에 설정한 제한으로 인해 결제할 수 없습니다. 은행에 문의하여 해외 또는 온라인 구매를 활성화하거나 다른 카드를 사용하세요. |
| `card_velocity_exceeded` | 카드의 거래 한도 또는 사용 가능 잔액을 초과했습니다. 더 적은 금액으로 시도하거나 다른 카드를 사용하세요. |
| `contact_issuer` | 이 거절에 대한 자세한 내용은 카드 발급사에 문의하세요. 카드 뒷면에 있는 고객센터 번호로 전화하세요. |
| `bank_declined` | 은행이 이 거래를 거절했습니다. 다른 카드를 사용하거나 은행에 문의하세요. |
| `regulatory_blocked` | 거주 지역의 규제로 인해 이 거래를 할 수 없습니다. 다른 결제 수단을 시도하거나 지원팀에 대안을 문의하세요. |
| `transaction_not_permitted` | 카드 발급사가 이 유형의 거래를 허용하지 않습니다. 다른 카드를 사용하거나 은행에 문의하여 이 거래 유형을 활성화하세요. |
| `card_type_not_supported` | 결제 대행사가 이 카드 유형을 지원하지 않습니다. 다른 카드를 사용해 보세요. |
| `issuer_not_found` | 카드 또는 청구 정보가 올바르지 않아 카드 발급사가 결제를 거절했습니다. 카드 번호, 만료일, 청구지 주소를 확인한 후 다시 시도하세요. |
| `closed_account` | 카드 계좌가 더 이상 개설되어 있지 않습니다. 다른 카드로 구매를 완료하세요. |
| `issuer_unavailable` | 결제 대행사가 이 결제를 승인하기 위해 카드 발급사에 연결할 수 없었습니다. 대개 일시적인 문제입니다. 몇 분 후 다시 시도하거나 다른 카드를 사용하세요. |
| `invalid_zip` | 청구지 우편번호가 카드 기록과 일치하지 않습니다. 카드 청구지 주소와 연결된 우편번호를 입력하세요. |
| `invalid_expiry_month` | 만료 월이 유효하지 않습니다. 유효한 월(01-12)을 입력하고 다시 시도하세요. |
| `invalid_expiry_year` | 만료 연도가 유효하지 않습니다. 유효한 2자리 또는 4자리 연도(예: 25 또는 2025)를 입력하고 다시 시도하세요. |
| `invalid_expiry` | 만료일이 유효하지 않습니다. <abbr title="월/연도">MM/YY</abbr> 형식으로 유효한 날짜를 입력하고 카드가 만료되지 않았는지 확인하세요. |
| `invalid_transaction` | 발급 은행이 이 거래를 거절했습니다. 잘못된 카드 번호, 만료된 카드, 유효하지 않은 카드, 잘못된 만료일, 청구지 주소 또는 우편번호 불일치, 짧은 시간 내 여러 번의 거래 시도 등이 원인일 수 있습니다. 카드 정보를 확인하고 다시 시도하세요. |
| `cannot_authorize` | 결제 대행사가 이 결제를 승인할 수 없었습니다. 다른 카드를 사용하거나 은행에 자세한 내용을 문의하세요. |
| `pin_required` | 이 카드는 거래에 개인 식별 번호(<abbr title="개인 식별 번호">PIN</abbr>)가 필요합니다. 호환되는 카드 리더기를 사용하거나 다른 카드를 사용해 보세요. |
| `pin_try_exceeded` | 잘못된 개인 식별 번호(<abbr title="개인 식별 번호">PIN</abbr>)를 너무 여러 번 입력했습니다. 보안을 위해 카드가 일시적으로 차단되었습니다. 은행에 문의하거나 다른 카드를 사용하세요. |
| `high_risk` | 보안 문제로 인해 결제가 차단되었습니다. 다른 카드를 사용하거나 지원팀에 도움을 요청하세요. |
| `test_mode_decline` | 테스트 카드 번호로 보입니다. 실제 신용카드 또는 체크카드로 구매를 완료하세요. |
| `merchant_blacklist` | 보안 검사로 인해 이 결제가 차단되었습니다. 다른 카드를 사용하거나 지원팀에 도움을 요청하세요. |
| `reenter_transaction` | 은행이 이 결제를 처리할 수 없었습니다. 다시 시도하거나, 다른 카드를 사용하거나, 은행에 자세한 내용을 문의하세요. |
| `invalid_pin` | 입력한 개인 식별 번호(<abbr title="개인 식별 번호">PIN</abbr>)가 올바르지 않습니다. 이 카드의 올바른 번호로 다시 시도하세요. |
| `pin_required_as` | 이 카드는 거래에 개인 식별 번호(<abbr title="개인 식별 번호">PIN</abbr>)가 필요합니다. 호환되는 카드 리더기를 사용하거나 다른 카드를 사용해 보세요. |
| `withdrawal_count_limit_exceeded` | 카드의 일일 거래 한도 또는 사용 가능 잔액을 초과했습니다. 내일 다시 시도하거나 다른 카드를 사용하세요. |
| `invalid_country` | 청구 국가가 카드 기록과 일치하지 않습니다. 청구지 주소의 국가를 확인하고 다시 시도하세요. |
| `issuer_error` | 은행이 문제를 감지했지만 원인을 확인할 수 없었습니다. 몇 분 후 다시 시도하거나 은행에 직접 도움을 요청하세요. |

## 결제 거절 후 진행 과정

고객의 결제가 거절되거나 실패하면 Whop은 결제를 복구하기 위해 여러 단계를 거칩니다.

* **구독 상태가 Past due로 변경됨**: 결제에 조치가 필요하지만, 이 상태로 인해 접근 권한이 즉시 취소되지는 않습니다
  * **Dashboard** > **Payments**로 이동하여 **Status**를 선택하고 **Past due**만 선택하세요
* **Whop이 고객에게 이메일 발송**: 고객은 결제 정보를 업데이트하라는 이메일을 받습니다. 고객이 할 수 있는 일은 [구독 결제 실패](https://docs.whop.com/ko/payments-and-billing/payment-issues/troubleshoot-failed-payments.md)에서 다룹니다
* **Whop이 결제 재시도**: Whop은 5일 동안 자동으로 청구를 재시도합니다
* **접근 권한이 일시 중지될 수 있음**: 설정에 따라 결제가 완료될 때까지 고객이 whop에 접근하지 못할 수 있습니다
  * **Dashboard** > **Settings** > **Checkout**으로 이동하세요
  * 멤버에게 **Access while past due**를 부여할지 선택하세요
* **Whop이 구독 취소**: 5일 후에도 결제가 계속 실패하면 Whop이 자동으로 구독을 취소합니다

## 거절된 결제를 해결하기 위해 할 수 있는 일

결제가 거절된 후 고객이 결제 수단을 업데이트하도록 돕고 대시보드에서 수동으로 결제를 재시도할 수 있습니다.

**1단계: 고객에게 결제 수단 업데이트 요청**

* 고객에게 연락하여 잔액이 충분하고 사용 가능한 결제 수단이 있는지 확인하세요
* 결제 수단을 업데이트하려면 고객에게 다음 단계를 따르도록 요청하세요.
  1. [https://whop.com/@me/settings/memberships](https://whop.com/@me/settings/memberships) 로 이동
  2. 비활성 멤버십 선택
  3. **Update payment method** 선택
  4. 새 카드 정보를 추가하고 저장

**2단계: 대시보드에서 수동으로 결제 재시도**

1. **Dashboard** > **Payments**로 이동합니다
2. **Status**를 선택하고 **Failed**만 선택합니다
3. 실패한 결제를 선택합니다
4. **Retry payment**를 선택합니다

결제가 성공적으로 처리되면 Whop이 고객의 접근 권한을 자동으로 복원합니다.


## Related topics

- [구독 결제 실패](https://docs.whop.com/ko/payments-and-billing/payment-issues/troubleshoot-failed-payments.md)
- [결제 거절 코드 설명](https://docs.whop.com/ko/payments-and-billing/payment-issues/payment-decline-reasons.md)
- [결제 처리 및 지급 수수료](https://docs.whop.com/ko/fees.md)
