Skip to main content
Manual Retry는 요청 시 결제 세부 정보 페이지 또는 API를 통해 실패한 구독 갱신 결제를 다시 시도합니다. 구독에 저장된 결제 수단으로 요금이 청구되며, 자동 Payment Retries 일정과는 독립적으로 실행됩니다.

수동 재시도란 무엇인가요?

갱신 결제가 실패하면 구독은 on_hold 상태로 전환됩니다. Payment Retries를 활성화한 경우 백오프 일정에 따라 요금 청구를 다시 시도합니다. 고객이 계정에 금액을 충전했다고 확인했거나 지원팀이 고객과 통화 중인 경우처럼, 결제가 지금은 성공할 것이라고 판단되는 때도 있습니다. Manual Retry는 다음 예약 시도를 위해 몇 시간 또는 며칠을 기다리는 대신 즉시 한 번 시도합니다.
  • 갱신 결제만 해당: Manual Retry는 구독이 on_hold 상태인 동안 구독 갱신 인보이스에 적용됩니다. 최초 결제, 일회성 결제, 플랜 변경 요금 및 온디맨드 요금은 대상이 아닙니다.
  • 고객 조치 불필요: 구독에 이미 저장된 결제 수단으로 요금이 청구됩니다.
  • 자동 재시도와 독립적: 수동 재시도는 자동 일정의 시도 횟수를 차감하지 않고, 다음 예약 재시도 시점을 변경하지 않으며, Payment Retries가 꺼져 있어도 작동합니다.
  • 결제가 아닌 인보이스를 다시 시도: 실패한 결제는 진입점일 뿐입니다. Dodo Payments는 해당 결제와 연결된 미결제 갱신 인보이스를 찾아 채무를 청구하므로, 인보이스에서 어떤 실패한 결제를 통해 재시도하더라도 결과는 같습니다.

대시보드에서 재시도

Owner 또는 Editor 역할을 가진 사용자만 수동 재시도를 보낼 수 있습니다.
1

Open the failed payment

Transactions → Payments로 이동한 다음 실패한 갱신 결제를 클릭하여 Transaction details 페이지를 엽니다.
2

Click Retry Payment Manually

오른쪽 상단에서 Retry Payment Manually를 클릭합니다. 이 버튼은 결제가 eligible 상태인 동안에만 사용할 수 있습니다.
3

Check the result

Dodo Payments는 시도를 위해 새 결제를 생성하며, 이 결제는 Activity Log에 표시됩니다. 요금 청구가 성공하면 구독은 active 상태로 돌아가고, 다음 청구일은 성공한 재시도 시점으로부터 한 청구 기간 후로 이동합니다. 결제 프로세서가 아직 요금 청구를 정산하지 않은 경우, payment.succeeded 또는 payment.failed webhook이 결과를 보고할 때까지 결제는 진행 중으로 표시됩니다.
오류 코드와 메시지, Activity Log 및 Retry Payment Manually 버튼이 표시된 실패한 결제의 Transaction details 페이지

Retry Payment Manually on the transaction details page of a failed renewal

Eligibility

Dodo Payments는 이 표의 모든 검사를 통과한 경우에만 수동 재시도를 보냅니다. Reason code 열은 API가 반환하는 값입니다. GET /payments/{payment_id}/retry에서는 reason로, POST /payments/{payment_id}/retry에서는 code 오류로 반환됩니다.
Manual Retry는 한 가지 측면에서 자동 재시도보다 조건이 더 엄격합니다. 구독이 on_hold 상태여야 합니다. 유예 기간 중인 past_due 구독은 이 검사를 통과하지 못합니다. 자동 재시도는 다른 비활성 상태에서도 계속 실행됩니다. Subscription Status Transitions을 참조하세요.
hard decline을 동일한 카드에 대해 재시도해도 성공할 수 없으며, 반복된 거절은 승인율에 악영향을 줍니다. 사유가 MANUAL_RETRY_HARD_DECLINE인 경우 고객에게 대신 결제 수단을 업데이트하도록 요청하세요. Subscription Dunning이 이 작업을 자동으로 수행합니다.

Retry Limits

각 갱신 인보이스에서는 수동 재시도를 3회 허용하며, 재시도 사이에는 쿨다운 시간이 적용됩니다. 이 한도는 test mode와 live mode 모두에 적용됩니다. 한도로 인해 재시도가 거부되면 API는 MANUAL_RETRY_LIMIT_REACHED(HTTP 429)를 반환하며, 오류 본문에는 code 및 message만 포함됩니다. 다음 재시도가 가능해지는 시점을 확인하려면 재시도 상태 확인을 수행하고 retry_available_at를 읽으세요. 세 번의 재시도를 모두 사용하면 null입니다. 자동 재시도는 이 한도에 포함되지 않으며, 수동 재시도도 자동 일정의 8회 시도에 포함되지 않습니다.

Manual vs. Automatic Retries

두 재시도 경로는 다음과 같이 다릅니다.

Retrying via the API

먼저 eligibility를 확인한 다음 재시도를 보냅니다. 두 endpoint 모두 실패한 결제의 ID를 받습니다.

Check Whether a Payment Can Be Retried

GET /payments/{payment_id}/retry는 eligible하지 않은 결제에 대해 오류를 반환하지 않습니다. 대신 reason 코드와 함께 can_retry: false를 반환하므로, 자체 대시보드 또는 지원 도구에 Dodo Payments 대시보드와 동일한 상태를 표시할 수 있습니다. 이 작업에는 Viewer 역할이 필요합니다.
Response

Send a Manual Retry

POST /payments/{payment_id}/retry는 새 결제를 생성하고 저장된 결제 수단으로 요금을 청구합니다. 이 작업에는 Editor 역할이 필요합니다. SDK 예시는 이전 예시의 client를 재사용합니다.
Response

Error Responses

재시도가 허용되지 않을 때 POST는 다음 HTTP 상태 중 하나를 반환합니다. Error Codes 참조에서 모든 코드를 설명합니다.

Webhooks

수동 재시도는 일반 결제를 생성하므로 다른 갱신 시도와 동일한 webhook이 실행됩니다. 이 이벤트의 payment object에서 retry_attempt는 1 이상이고 subscription_id가 설정됩니다. 이는 자동 재시도와 동일합니다. payment object에는 수동 시도를 표시하는 필드가 없으므로, 수동 시도와 예약된 시도를 구분해야 한다면 재시도 응답의 payment_id를 보관하세요.

Payment Webhook Payloads

결제 이벤트의 전체 payload 스키마입니다.

Subscription Payment Retries

수동 재시도와 함께 실행되는 자동 백오프 일정입니다.

Subscription Dunning

hard decline 후 결제 수단을 업데이트하도록 고객에게 이메일을 보냅니다.

Handle Payment Failures

거절 코드를 읽고 재시도할 가치가 있는 시점을 판단합니다.

Error Codes

모든 MANUAL_RETRY_* 코드, 해당 트리거 및 메시지입니다.
마지막 수정일 2026년 9월 26일