Menangani Kegagalan Pembayaran

Ketika pembayaran gagal, Dodo Payments memberi tahu Anda mengapa melalui error_code yang terstandarisasi dan error_message yang dapat dibaca manusia. Panduan ini menjelaskan cara membaca kolom tersebut, menentukan apakah percobaan ulang layak dilakukan, dan memulihkan pembayaran tanpa mengekspos informasi sensitif kepada pelanggan.

Bagaimana Dodo Payments Melaporkan Kegagalan

Setiap pembayaran yang gagal — baik checkout satu kali maupun perpanjangan langganan — memiliki kolom kegagalan yang sama pada objek pembayaran:

Field	Type	Description
`status`	string	`failed` untuk pembayaran yang gagal. Status non-sukses lainnya mencakup `cancelled`, `requires_customer_action`, dan `requires_payment_method`.
`error_code`	string \| null	Alasan kegagalan terstandarisasi, misalnya `INSUFFICIENT_FUNDS` atau `PROCESSING_ERROR`. Lihat referensi Transaction Failures untuk daftar lengkap.
`error_message`	string \| null	Penjelasan kegagalan yang dapat dibaca manusia, ditulis untuk Anda, bukan untuk customer Anda. Untuk `error_code` yang terstandarisasi, ini berupa judul utama ditambah tindakan yang direkomendasikan, bukan teks mentah dari processor.
`retry_attempt`	integer	`0` untuk charge asli. `1` atau lebih tinggi menunjukkan percobaan ulang renewal subscription yang terjadwal.

error_code dan error_message adalah null sampai pembayaran benar-benar gagal. Selalu periksa status terlebih dahulu, lalu baca kolom error.

error_message dari merchant API adalah teks yang ditujukan untuk merchant. Teks ini dapat menyebutkan alasan sebenarnya dari penolakan, termasuk alasan terkait fraud, jadi jangan pernah menampilkannya langsung kepada customer. Petakan error_code ke teks Anda sendiri yang aman bagi customer, seperti yang ditunjukkan dalam Menampilkan Error kepada Customer dengan Aman.

Webhook `payment.failed`

Cara paling andal untuk mendeteksi kegagalan adalah webhook payment.failed. Event ini membungkus seluruh objek payment dalam 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 minimal membaca error_code dan melakukan routing berdasarkan nilainya:

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 renewal — Dodo retries soft declines for you
      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 renewal — Dodo retries soft declines for you
            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}

Selalu verifikasi signature webhook sebelum memprosesnya. Lihat panduan Webhooks untuk penyiapan lengkap, termasuk verifikasi signature dan idempotency.

Tentukan Apakah Perlu Retry: Soft vs. Hard Decline

error_code memberi tahu apakah retry dengan metode pembayaran yang sama layak dilakukan.

Jenis decline	Artinya	Tindakan yang harus dilakukan
Soft decline	Sementara atau dapat diperbaiki (misalnya `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Melakukan retry — setelah jeda, atau setelah customer memperbaiki input mereka — dapat berhasil.
Hard decline	Bersifat terminal (misalnya `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Jangan melakukan retry pada kartu yang sama. Minta customer menggunakan metode pembayaran lain.

Referensi Transaction Failures mencantumkan jenis decline dan tindakan yang direkomendasikan untuk setiap error_code.

Menangani Kegagalan Saat Checkout vs. Saat Renewal

Cara pemulihan yang Anda lakukan bergantung pada apakah customer sedang hadir.

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

Customer sedang aktif melakukan checkout. Tampilkan pesan yang jelas dan izinkan mereka melakukan retry segera atau menggunakan kartu lain.

requires_payment_method — customer tidak pernah memberikan metode pembayaran: mereka tidak memasukkan detail kartu, atau diminta memasukkannya tetapi tidak melakukan tindakan apa pun. Ini biasanya merupakan drop-off saat checkout, bukan decline — hubungi kembali customer agar menyelesaikan pembayaran (lihat Pemulihan Abandoned Cart).
requires_customer_action — autentikasi tambahan (seperti 3DS) diperlukan; minta customer menyelesaikannya. Lihat penanganan 3D Secure.

Customer tidak hadir, sehingga Anda tidak dapat meminta tindakan dari mereka secara real time. Saat renewal gagal, subscription berpindah ke on_hold dan subscription.on_hold dipicu.

Soft decline dicoba ulang secara otomatis oleh Subscription Payment Retries.
Hard decline (dan retry yang telah habis) paling baik dipulihkan dengan Subscription Dunning, yang mengirim email kepada customer untuk memperbarui metode pembayaran mereka.

Lihat Subscription Integration Guide untuk alur lengkap on-hold → reactivate.

Melakukan Retry pada Pembayaran yang Gagal

Subscriptions: Aktifkan Subscription Payment Retries untuk memulihkan soft decline tanpa pekerjaan integrasi. Anda juga dapat memicu pemulihan dengan meminta customer memperbarui metode pembayaran mereka melalui Update Payment Method API, yang akan menagihkan tunggakan apa pun.
Pembayaran satu kali: Kirim ulang checkout atau payment_link agar customer dapat mencoba lagi dengan metode lain. Tidak ada retry otomatis untuk pembayaran satu kali.

Jangan melakukan retry untuk hard decline pada kartu yang sama. Jaringan kartu dapat menandai decline berulang sebagai tindakan penyalahgunaan, yang menurunkan tingkat otorisasi Anda.

Menampilkan Error kepada Customer dengan Aman

Tampilkan pesan yang ramah kepada customer — jangan pernah menampilkan error_code mentah, dan jangan pernah menampilkan error_message yang ditujukan untuk merchant.

Pada permukaan yang dikontrol oleh Dodo Payments — checkout, Customer Portal, dan email dunning — pemetaan ini sudah dilakukan untuk Anda, termasuk fallback ke pesan umum untuk decline terkait fraud. Anda hanya memerlukan pemetaan di bawah ini ketika menampilkan kegagalan dalam produk Anda sendiri.

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

Jangan pernah mengungkapkan alasan sebenarnya untuk STOLEN_CARD, LOST_CARD, PICKUP_CARD, atau FRAUDULENT. Menampilkan informasi ini dapat memberi petunjuk kepada pelaku fraud. Tampilkan pesan decline umum dan hanya catat error_code yang spesifik secara internal.

Terkait

Transaction Failures

Setiap kode decline, jenisnya, dan tindakan yang direkomendasikan.

Error Codes

Error API dan logika bisnis yang bukan merupakan card decline.

Subscription Payment Retries

Pemulihan otomatis soft decline pada renewal subscription.

Subscription Dunning

Rangkaian email untuk memulihkan hard decline.

Payment Webhooks

Skema payload lengkap untuk event pembayaran.

Testing Failures

Kartu pengujian yang menyimulasikan decline dan kegagalan renewal.

Integration Guides

Billing Deconstructions

Cookbooks

Bagaimana Dodo Payments Melaporkan Kegagalan

Webhook `payment.failed`

Tentukan Apakah Perlu Retry: Soft vs. Hard Decline

Menangani Kegagalan Saat Checkout vs. Saat Renewal

Melakukan Retry pada Pembayaran yang Gagal

Menampilkan Error kepada Customer dengan Aman

Terkait

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Bagaimana Dodo Payments Melaporkan Kegagalan

​Webhook payment.failed

​Tentukan Apakah Perlu Retry: Soft vs. Hard Decline

​Menangani Kegagalan Saat Checkout vs. Saat Renewal

​Melakukan Retry pada Pembayaran yang Gagal

​Menampilkan Error kepada Customer dengan Aman

​Terkait

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Bagaimana Dodo Payments Melaporkan Kegagalan

Webhook `payment.failed`

Tentukan Apakah Perlu Retry: Soft vs. Hard Decline

Menangani Kegagalan Saat Checkout vs. Saat Renewal

Melakukan Retry pada Pembayaran yang Gagal

Menampilkan Error kepada Customer dengan Aman

Terkait