Menangani Kegagalan Pembayaran

Saat pembayaran gagal, Dodo Payments menyediakan error_code standar dan error_message yang mudah dipahami. Panduan ini menunjukkan cara membaca kolom tersebut, menentukan apakah perlu mencoba lagi, dan memulihkan pembayaran dengan aman.

Bagaimana Dodo Payments Melaporkan Kegagalan

Setiap pembayaran yang gagal memiliki kolom berikut pada objek pembayaran:

Kolom	Tipe	Deskripsi
`status`	string	`failed` untuk pembayaran yang gagal. Status non-sukses lainnya: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Alasan kegagalan standar, misalnya `INSUFFICIENT_FUNDS` atau `PROCESSING_ERROR`. Lihat Transaction Failures untuk daftar lengkapnya.
`error_message`	string \| null	Penjelasan untuk merchant dengan tindakan yang direkomendasikan. Bukan untuk pelanggan.
`retry_attempt`	integer	`0` untuk tagihan asli. `1` atau lebih tinggi untuk percobaan ulang perpanjangan subscription yang dijadwalkan.

error_code dan error_message adalah null hingga pembayaran gagal. Selalu periksa status terlebih dahulu.

error_message ditujukan untuk merchant dan dapat mengungkapkan alasan terkait fraud. Jangan pernah menampilkannya kepada pelanggan. Sebagai gantinya, petakan error_code ke teks yang aman bagi pelanggan (lihat Tampilkan Error kepada Pelanggan dengan Aman).

Webhook `payment.failed`

Webhook payment.failed adalah cara paling andal untuk mendeteksi kegagalan. Event tersebut membungkus objek pembayaran lengkap 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 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}

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	Contoh	Tindakan
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Coba lagi setelah beberapa saat atau setelah pelanggan memperbaiki inputnya.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Jangan mencoba lagi dengan kartu yang sama. Minta pelanggan menggunakan metode pembayaran yang berbeda.

Lihat Transaction Failures untuk daftar lengkap jenis decline dan tindakan yang direkomendasikan.

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)

Pelanggan sedang aktif melakukan checkout. Tampilkan pesan yang jelas dan izinkan mereka mencoba lagi atau menggunakan kartu lain.

requires_payment_method — pelanggan tidak pernah memberikan metode pembayaran. Ini biasanya merupakan pelanggan yang meninggalkan checkout, bukan decline. Hubungi kembali pelanggan agar menyelesaikan pembayaran (lihat Pemulihan Keranjang yang Ditinggalkan).
requires_customer_action — autentikasi tambahan (seperti 3DS) diperlukan. Minta pelanggan menyelesaikannya. Lihat 3D Secure.

Pelanggan tidak sedang berada di tempat. Saat perpanjangan gagal, subscription berpindah ke on_hold dan subscription.on_hold dipicu. Jika bisnis Anda memiliki masa tenggang, subscription akan berpindah ke past_due terlebih dahulu (subscription.past_due) dan akses tetap tersedia hingga masa tenggang berakhir.

Soft decline dicoba lagi secara otomatis jika Anda mengaktifkan Subscription Payment Retries (dinonaktifkan secara default). Percobaan ulang hanya mencakup perpanjangan yang dijadwalkan, bukan tagihan berdasarkan permintaan.
Hard decline (dan percobaan ulang yang telah habis) pada perpanjangan yang dijadwalkan dipulihkan dengan Subscription Dunning, yang mengirim email kepada pelanggan untuk memperbarui metode pembayaran mereka. Untuk kegagalan tagihan berdasarkan permintaan, lihat On-Demand Subscriptions.

Lihat Subscription Integration Guide untuk alur lengkap dari status on-hold → aktivasi kembali.

Melakukan Retry pada Pembayaran yang Gagal

Subscriptions: Aktifkan Subscription Payment Retries untuk memulihkan soft decline secara otomatis. Untuk mencoba lagi segera tanpa menunggu jadwal, gunakan Manual Payment Retry dari dashboard atau API. Anda juga dapat memicu pemulihan dengan meminta pelanggan memperbarui metode pembayaran mereka melalui Update Payment Method API, yang akan menagih tunggakan apa pun. Pembayaran satu kali: Kirim ulang checkout atau payment_link agar pelanggan dapat mencoba lagi dengan metode yang berbeda. Tidak ada percobaan ulang otomatis untuk pembayaran satu kali.

Jangan mencoba lagi hard decline dengan kartu yang sama. Jaringan kartu menandai decline berulang sebagai tindakan penyalahgunaan, yang menurunkan tingkat otorisasi Anda.

Tampilkan Error kepada Pelanggan dengan Aman

Tampilkan pesan yang ramah kepada pelanggan, jangan pernah menampilkan error_code mentah atau error_message yang ditujukan untuk merchant.

Pada antarmuka yang dikendalikan Dodo Payments (checkout, Customer Portal, email dunning), pemetaan ini sudah dilakukan untuk Anda, termasuk fallback ke pesan umum untuk decline terkait fraud. Anda hanya memerlukan pemetaan di bawah ini jika 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 alasan tersebut dapat memberi petunjuk kepada pelaku fraud. Tampilkan pesan decline umum dan catat error_code spesifik hanya secara internal.

Terkait

Transaction Failures

Setiap kode decline, jenisnya, dan tindakan yang direkomendasikan.

Error Codes

Error API dan logika bisnis yang bukan merupakan decline kartu.

Subscription Payment Retries

Pemulihan otomatis soft decline pada perpanjangan subscription.

Subscription Dunning

Urutan email yang memulihkan hard decline.

Payment Webhooks

Skema payload lengkap untuk event pembayaran.

Testing Failures

Kartu pengujian yang menyimulasikan decline dan kegagalan perpanjangan.

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

Tampilkan Error kepada Pelanggan 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

​Tampilkan Error kepada Pelanggan 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

Tampilkan Error kepada Pelanggan dengan Aman

Terkait