भुगतान विफलताओं को संभालें

जब कोई भुगतान विफल होता है, Dodo Payments एक मानकीकृत error_code और मानव-पठनीय error_message प्रदान करता है। यह गाइड दिखाती है कि इन फ़ील्ड को कैसे पढ़ें, पुनः प्रयास करना है या नहीं यह कैसे तय करें, और भुगतान को सुरक्षित रूप से कैसे पुनर्प्राप्त करें।

Dodo Payments विफलता की रिपोर्ट कैसे करता है

हर विफल भुगतान में payment object पर ये फ़ील्ड होते हैं:

Field	Type	Description
`status`	string	विफल भुगतान के लिए `failed`। अन्य गैर-सफल स्थितियाँ: `cancelled`, `requires_customer_action`, `requires_payment_method`।
`error_code`	string \| null	मानकीकृत विफलता कारण, जैसे `INSUFFICIENT_FUNDS` या `PROCESSING_ERROR`। पूरी सूची के लिए Transaction Failures देखें।
`error_message`	string \| null	Merchant के लिए दिखाई जाने वाली व्याख्या और सुझाई गई कार्रवाई। ग्राहकों के लिए नहीं।
`retry_attempt`	integer	मूल charge के लिए `0`। निर्धारित subscription renewal retries के लिए `1` या उससे अधिक।

error_code और error_message तब तक null रहते हैं, जब तक कोई भुगतान विफल न हो जाए। हमेशा पहले status जाँचें।

error_message Merchant के लिए दिखाई देता है और धोखाधड़ी से जुड़े कारण प्रकट कर सकता है। इसे ग्राहकों को कभी न दिखाएँ। इसके बजाय error_code को ग्राहकों के लिए सुरक्षित भाषा में मैप करें (देखें Surface Errors to Customers Safely)।

`payment.failed` Webhook

विफलता का पता लगाने के लिए payment.failed webhook सबसे विश्वसनीय तरीका है। यह event पूरे payment object को data में लपेटता है:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

एक न्यूनतम handler error_code को पढ़ता है और उसके आधार पर route करता है:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

Processing से पहले हमेशा webhook signature verify करें। Signature verification और idempotency सहित पूरे setup के लिए Webhooks guide देखें।

तय करें कि Retry करना है या नहीं: Soft बनाम Hard Declines

error_code आपको बताता है कि उसी payment method को retry करना उपयोगी होगा या नहीं।

अस्वीकृति का प्रकार	उदाहरण	कार्रवाई
सॉफ्ट अस्वीकृति	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	कुछ समय बाद या ग्राहक द्वारा अपना input ठीक करने के बाद पुनः प्रयास करें।
हार्ड अस्वीकृति	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	उसी card पर पुनः प्रयास न करें। ग्राहक से अलग payment method माँगें।

अस्वीकृति के प्रकारों और सुझाई गई कार्रवाइयों की पूरी सूची के लिए Transaction Failures देखें।

Checkout के दौरान बनाम Renewal पर Failures को Handle करना

आप recovery कैसे करेंगे, यह इस बात पर निर्भर करता है कि customer मौजूद है या नहीं।

At checkout (customer present)
On subscription renewal (customer not present)

ग्राहक सक्रिय रूप से checkout कर रहा है। स्पष्ट संदेश दिखाएँ और उसे फिर से प्रयास करने या किसी अन्य card का उपयोग करने दें।

requires_payment_method — ग्राहक ने कोई payment method नहीं दिया। यह आमतौर पर checkout drop-off होता है, अस्वीकृति नहीं। भुगतान पूरा करने के लिए ग्राहक से दोबारा संपर्क करें (देखें Abandoned Cart Recovery)।
requires_customer_action — अतिरिक्त authentication (जैसे 3DS) आवश्यक है। ग्राहक से इसे पूरा करने के लिए कहें। 3D Secure देखें।

ग्राहक मौजूद नहीं है। जब renewal विफल होता है, subscription on_hold स्थिति में चला जाता है और subscription.on_hold trigger होता है। यदि आपके business में grace period है, तो यह पहले past_due (subscription.past_due) में चला जाता है और grace period समाप्त होने तक access बनाए रखता है।

निर्धारित renewals पर Subscription Payment Retries चालू करने पर Soft declines का अपने-आप पुनः प्रयास किया जाता है (डिफ़ॉल्ट रूप से बंद)। Retries केवल निर्धारित renewals पर लागू होते हैं, on-demand charges पर नहीं।
निर्धारित renewals पर Hard declines (और समाप्त हो चुके retries) को Subscription Dunning के माध्यम से recover किया जाता है, जो ग्राहक को अपना payment method अपडेट करने के लिए email भेजता है। On-demand charge failures के लिए On-Demand Subscriptions देखें।

पूरे on-hold → reactivate flow के लिए Subscription Integration Guide देखें।

Failed Payment को Retry करना

Subscriptions: Soft declines को अपने-आप recover करने के लिए Subscription Payment Retries सक्षम करें। Schedule का इंतज़ार करने के बजाय तुरंत retry करने के लिए dashboard या API से Manual Payment Retry का उपयोग करें। ग्राहक से Update Payment Method API के माध्यम से अपना payment method अपडेट करवाकर भी recovery trigger कर सकते हैं, जिससे कोई भी बकाया राशि charge हो जाती है। One-time payments: checkout या payment_link फिर से भेजें, ताकि ग्राहक किसी अन्य method से दोबारा प्रयास कर सके। One-time payments के लिए कोई automatic retry नहीं है।

उसी card पर hard declines का पुनः प्रयास न करें। Card networks बार-बार होने वाली अस्वीकृतियों को abusive मानकर flag करते हैं, जिससे आपकी authorization rate प्रभावित होती है।

ग्राहकों को सुरक्षित रूप से त्रुटियाँ दिखाएँ

ग्राहकों को मित्रवत संदेश दिखाएँ, raw error_code या Merchant के लिए दिखाई देने वाले error_message को कभी नहीं।

Dodo Payments-नियंत्रित surfaces (checkout, Customer Portal, dunning emails) पर यह mapping आपके लिए पहले से की गई है, जिसमें fraud-related declines के लिए generic message का fallback भी शामिल है। नीचे दी गई mapping की आवश्यकता केवल तब है, जब आप अपने product में failures render करते हैं।

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

STOLEN_CARD, LOST_CARD, PICKUP_CARD या FRAUDULENT का वास्तविक कारण कभी उजागर न करें। इन्हें दिखाने से धोखाधड़ी करने वाले व्यक्ति को सतर्क किया जा सकता है। generic decline message दिखाएँ और विशिष्ट error_code को केवल आंतरिक रूप से log करें।

Transaction Failures

हर decline code, उसका प्रकार और सुझाई गई कार्रवाई।

Error Codes

API और business-logic errors जो card declines नहीं हैं।

Subscription Payment Retries

Subscription renewals पर soft declines की automatic recovery।

Subscription Dunning

Hard declines को recover करने वाले email sequences।

Payment Webhooks

Payment events के लिए पूर्ण payload schema।

Testing Failures

Declines और renewal failures को simulate करने वाले test cards।

Integration Guides

Billing Deconstructions

Cookbooks

भुगतान विफलताओं को संभालें

Dodo Payments विफलता की रिपोर्ट कैसे करता है

`payment.failed` Webhook

तय करें कि Retry करना है या नहीं: Soft बनाम Hard Declines

Checkout के दौरान बनाम Renewal पर Failures को Handle करना

Failed Payment को Retry करना

ग्राहकों को सुरक्षित रूप से त्रुटियाँ दिखाएँ

संबंधित

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Dodo Payments विफलता की रिपोर्ट कैसे करता है

​payment.failed Webhook

​तय करें कि Retry करना है या नहीं: Soft बनाम Hard Declines

​Checkout के दौरान बनाम Renewal पर Failures को Handle करना

​Failed Payment को Retry करना

​ग्राहकों को सुरक्षित रूप से त्रुटियाँ दिखाएँ

​संबंधित

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Dodo Payments विफलता की रिपोर्ट कैसे करता है

`payment.failed` Webhook

तय करें कि Retry करना है या नहीं: Soft बनाम Hard Declines

Checkout के दौरान बनाम Renewal पर Failures को Handle करना

Failed Payment को Retry करना

ग्राहकों को सुरक्षित रूप से त्रुटियाँ दिखाएँ

संबंधित