Xử Lý Thanh Toán Thất Bại

Khi một khoản thanh toán thất bại, Dodo Payments cung cấp error_code được chuẩn hóa và error_message ở dạng dễ đọc. Hướng dẫn này chỉ ra cách đọc các trường đó, quyết định có nên thử lại hay không và khôi phục khoản thanh toán an toàn.

Cách Dodo Payments Báo Cáo Một Thất Bại

Mỗi khoản thanh toán thất bại đều có các trường sau trên payment object:

Field	Type	Description
`status`	string	`failed` cho một khoản thanh toán thất bại. Các trạng thái không thành công khác: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Lý do thất bại được chuẩn hóa, ví dụ `INSUFFICIENT_FUNDS` hoặc `PROCESSING_ERROR`. Xem Transaction Failures để biết danh sách đầy đủ.
`error_message`	string \| null	Giải thích dành cho merchant kèm hành động được đề xuất. Không dành cho khách hàng.
`retry_attempt`	integer	`0` cho khoản charge ban đầu. `1` trở lên cho các lần thử lại khi gia hạn subscription theo lịch.

error_code và error_message là null cho đến khi một khoản thanh toán thất bại. Luôn kiểm tra status trước.

error_message dành cho merchant và có thể tiết lộ các lý do liên quan đến gian lận. Tuyệt đối không hiển thị trường này cho khách hàng. Thay vào đó, hãy ánh xạ error_code sang nội dung an toàn cho khách hàng (xem Hiển thị lỗi cho khách hàng an toàn).

Webhook `payment.failed`

Webhook payment.failed là cách đáng tin cậy nhất để phát hiện lỗi. Event chứa toàn bộ payment object trong 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"
    }
  }
}

Một handler tối thiểu sẽ đọc error_code và định tuyến dựa trên giá trị đó:

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}

Luôn xác minh chữ ký của webhook trước khi xử lý. Xem hướng dẫn Webhooks để biết toàn bộ quy trình thiết lập, bao gồm xác minh chữ ký và idempotency.

Quyết định có nên Retry hay không: Soft Decline và Hard Decline

error_code cho biết việc retry cùng payment method có đáng thực hiện hay không.

Decline type	Examples	Action
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Thử lại sau một khoảng thời gian hoặc sau khi khách hàng sửa thông tin đã nhập.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Không thử lại với cùng một card. Yêu cầu khách hàng sử dụng payment method khác.

Xem Transaction Failures để biết danh sách đầy đủ các loại decline và hành động được đề xuất.

Xử lý lỗi tại Checkout và khi Renewal

Cách khôi phục phụ thuộc vào việc customer có đang hiện diện hay không.

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

Khách hàng đang chủ động thực hiện checkout. Hiển thị thông báo rõ ràng và cho phép họ thử lại hoặc sử dụng card khác.

requires_payment_method — khách hàng chưa cung cấp payment method. Đây thường là trường hợp rời bỏ checkout, không phải decline. Thu hút lại khách hàng để hoàn tất thanh toán (xem Khôi phục giỏ hàng bị bỏ quên).
requires_customer_action — cần xác thực bổ sung (chẳng hạn như 3DS). Yêu cầu khách hàng hoàn tất bước này. Xem 3D Secure.

Khách hàng không có mặt. Khi gia hạn thất bại, subscription chuyển sang on_hold và subscription.on_hold được kích hoạt. Nếu doanh nghiệp của bạn có thời gian gia hạn, subscription trước tiên sẽ chuyển sang past_due (subscription.past_due) và vẫn duy trì quyền truy cập cho đến khi thời gian gia hạn kết thúc.

Soft decline được tự động thử lại nếu bạn bật Subscription Payment Retries (mặc định tắt). Các lần thử lại chỉ áp dụng cho những lần gia hạn theo lịch, không áp dụng cho các khoản charge theo yêu cầu.
Hard decline (và các lần thử lại đã hết) trong những lần gia hạn theo lịch sẽ được khôi phục bằng Subscription Dunning, tính năng gửi email cho khách hàng để cập nhật payment method. Đối với lỗi của các khoản charge theo yêu cầu, xem On-Demand Subscriptions.

Xem Subscription Integration Guide để biết đầy đủ quy trình on-hold → reactivate.

Retry Payment Thất bại

Subscriptions: Bật Subscription Payment Retries để tự động khôi phục các trường hợp soft decline. Để thử lại ngay thay vì chờ theo lịch, hãy sử dụng Manual Payment Retry từ dashboard hoặc API. Bạn cũng có thể kích hoạt quá trình khôi phục bằng cách yêu cầu khách hàng cập nhật payment method thông qua Update Payment Method API, thao tác này sẽ charge mọi khoản còn nợ. One-time payments: Gửi lại checkout hoặc payment_link để khách hàng có thể thử lại bằng payment method khác. One-time payments không được tự động retry.

Không thử lại hard decline với cùng một card. Các mạng lưới thẻ sẽ đánh dấu những lần decline lặp lại là hành vi lạm dụng, làm giảm authorization rate của bạn.

Hiển thị lỗi cho khách hàng an toàn

Hiển thị cho khách hàng một thông báo thân thiện, không bao giờ hiển thị error_code thô hoặc error_message dành cho merchant.

Trên các giao diện do Dodo Payments kiểm soát (checkout, Customer Portal, email dunning), việc ánh xạ này đã được thực hiện sẵn cho bạn, bao gồm cả cơ chế dự phòng sang thông báo chung đối với các trường hợp decline liên quan đến gian lận. Bạn chỉ cần sử dụng ánh xạ bên dưới khi hiển thị lỗi trong sản phẩm của riêng mình.

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.";
}

Không bao giờ tiết lộ lý do thực sự của STOLEN_CARD, LOST_CARD, PICKUP_CARD hoặc FRAUDULENT. Việc hiển thị các lý do này có thể cảnh báo cho kẻ gian. Hãy hiển thị thông báo decline chung và chỉ ghi log error_code cụ thể trong nội bộ.

Liên quan

Transaction Failures

Mọi decline code, loại decline và hành động được đề xuất.

Error Codes

Các lỗi API và logic nghiệp vụ không phải là card decline.

Subscription Payment Retries

Tự động khôi phục soft decline trong các lần gia hạn subscription.

Subscription Dunning

Các chuỗi email khôi phục hard decline.

Payment Webhooks

Schema payload đầy đủ cho các payment event.

Testing Failures

Các test card mô phỏng decline và lỗi gia hạn.

Integration Guides

Billing Deconstructions

Cookbooks

Cách Dodo Payments Báo Cáo Một Thất Bại

Webhook `payment.failed`

Quyết định có nên Retry hay không: Soft Decline và Hard Decline

Xử lý lỗi tại Checkout và khi Renewal

Retry Payment Thất bại

Hiển thị lỗi cho khách hàng an toàn

Liên quan

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Cách Dodo Payments Báo Cáo Một Thất Bại

​Webhook payment.failed

​Quyết định có nên Retry hay không: Soft Decline và Hard Decline

​Xử lý lỗi tại Checkout và khi Renewal

​Retry Payment Thất bại

​Hiển thị lỗi cho khách hàng an toàn

​Liên quan

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Cách Dodo Payments Báo Cáo Một Thất Bại

Webhook `payment.failed`

Quyết định có nên Retry hay không: Soft Decline và Hard Decline

Xử lý lỗi tại Checkout và khi Renewal

Retry Payment Thất bại

Hiển thị lỗi cho khách hàng an toàn

Liên quan