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이 결과를 보고할 때까지 결제는 진행 중으로 표시됩니다.
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을 참조하세요.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 스키마입니다.
Related
Subscription Payment Retries
수동 재시도와 함께 실행되는 자동 백오프 일정입니다.
Subscription Dunning
hard decline 후 결제 수단을 업데이트하도록 고객에게 이메일을 보냅니다.
Handle Payment Failures
거절 코드를 읽고 재시도할 가치가 있는 시점을 판단합니다.
Error Codes
모든
MANUAL_RETRY_* 코드, 해당 트리거 및 메시지입니다.