Kegagalan Transaksi

Ikhtisar

Dodo Payments mengembalikan alasan kegagalan yang mendetail setiap kali percobaan pembayaran tidak berhasil. Alasan-alasan ini distandarisasi di seluruh metode dan penyedia pembayaran, sehingga Anda dapat menerapkan penanganan yang konsisten dalam aplikasi Anda. Ketika pembayaran gagal, webhook payment.failed dan objek pembayaran menampilkan:

error_code — alasan kegagalan terstandarisasi dari tabel di bawah.
error_message — penjelasan yang mudah dipahami manusia dan ditulis untuk Anda, merchant. Jika error_code merupakan salah satu kode terstandarisasi di bawah, ini berupa judul utama serta tindakan yang direkomendasikan, bukan teks mentah dari pemroses pembayaran.
retry_attempt — 0 untuk tagihan asli, 1 atau lebih tinggi untuk setiap percobaan ulang perpanjangan langganan terjadwal.

Memahami alasan kegagalan ini memungkinkan Anda memberikan umpan balik yang jelas kepada pelanggan, memutuskan apakah percobaan ulang layak dilakukan, dan memulihkan lebih banyak pendapatan.

Teks untuk Merchant vs. Teks untuk Customer

Setiap kode kegagalan terstandarisasi dipetakan ke dua pesan yang berbeda, sehingga audiens yang tepat melihat tingkat detail yang sesuai:

Audiens	Tempat ditampilkan	Isi pesan
Anda	`error_message` pada pembayaran, halaman detail pembayaran di dashboard, dan email pembayaran gagal untuk merchant	Alasan sebenarnya beserta tindakan yang direkomendasikan, misalnya “Kartu belum diaktifkan oleh pemegang kartu. Minta customer mengaktifkannya melalui bank mereka, lalu coba lagi.”
Customer Anda	Layar kegagalan checkout, Customer Portal, dan email dunning	Penjelasan singkat dengan bahasa sederhana yang dapat ditindaklanjuti, misalnya “Kartu Anda belum diaktifkan. Silakan aktifkan melalui bank Anda dan coba lagi.”

Customer Portal mengembalikan teks yang ditujukan kepada customer dalam error_message, sedangkan merchant API mengembalikan teks untuk merchant pada pembayaran yang sama. error_code identik pada keduanya.

Handle Payment Failures

Panduan developer langkah demi langkah untuk membaca kode ini dari webhook dan API, menampilkannya kepada customer, serta menentukan kapan harus mencoba kembali.

Soft Decline vs. Hard Decline

Setiap kode kegagalan termasuk dalam salah satu dari dua kategori. Pembedaan ini menentukan apakah Anda harus mencoba kembali dengan metode pembayaran yang sama atau meminta customer menggunakan metode baru.

Jenis decline	Artinya	Tindakan	Contoh
Soft decline	Bersifat sementara atau dapat diperbaiki — kartu yang sama dapat berhasil pada percobaan berikutnya atau setelah customer memperbaiki input mereka.	Aman untuk dicoba kembali (setelah jeda atau setelah customer memperbaiki detail mereka).	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Hard decline	Bersifat final — mencoba kembali dengan kartu yang sama tidak akan mengubah hasil.	Jangan mencoba kembali dengan kartu yang sama. Minta customer menggunakan metode pembayaran lain atau menghubungi bank mereka.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`

Untuk perpanjangan langganan, Dodo Payments menerapkan pembedaan ini secara otomatis: soft decline dicoba kembali oleh Subscription Payment Retries, sedangkan hard decline langsung mengakhiri rangkaian percobaan ulang dan sebaiknya ditangani dengan Subscription Dunning.

Jangan pernah mengungkapkan alasan sebenarnya untuk STOLEN_CARD, LOST_CARD, PICKUP_CARD, atau FRAUDULENT kepada customer. Menampilkan informasi ini dapat memberi petunjuk kepada pelaku penipuan. Selalu tampilkan pesan decline umum kepada customer (misalnya, “Kartu Anda ditolak. Silakan hubungi bank Anda atau gunakan kartu lain.”) dan catat kode spesifik hanya secara internal.Dodo Payments sudah menerapkan aturan ini pada permukaan yang dikontrolnya: untuk keempat kode ini, checkout, Customer Portal, dan email dunning selalu menggunakan pesan decline umum sebagai fallback, sedangkan teks Anda tetap menyimpan alasan sebenarnya. Terapkan aturan yang sama di mana pun Anda menampilkan error_message dari merchant API kepada customer.

Alasan Kegagalan Transaksi

Tabel berikut mencantumkan setiap kode kegagalan, jenis decline, apakah customer dapat menyelesaikannya, deskripsi, dan tindakan yang direkomendasikan.

Kode Kegagalan	Jenis	Kesalahan User	Deskripsi	Tindakan yang Direkomendasikan
`AUTHENTICATION_FAILURE`	Soft	Ya	Autentikasi gagal selama transaksi	Minta customer mencoba lagi dan menyelesaikan autentikasi 3DS, atau menggunakan kartu lain
`AUTHENTICATION_REQUIRED`	Soft	Ya	Autentikasi tambahan diperlukan untuk menyelesaikan transaksi	Minta customer menyelesaikan autentikasi 3DS. Untuk perpanjangan langganan, minta customer kembali dan melakukan autentikasi
`AUTHENTICATION_TIMEOUT`	Soft	Ya	Proses autentikasi kehabisan waktu	Minta customer mencoba lagi dan segera menyelesaikan autentikasi
`CARD_DECLINED`	Soft	Tidak	Kartu ditolak oleh bank penerbit tanpa alasan spesifik (generic decline)	Minta customer mencoba lagi, menghubungi bank mereka, atau menggunakan kartu lain
`CARD_NOT_ACTIVATED`	Soft	Ya	Kartu belum diaktifkan oleh pemegang kartu	Minta customer mengaktifkan kartu melalui bank mereka, lalu coba lagi
`CARD_VELOCITY_EXCEEDED`	Soft	Ya	Terlalu banyak transaksi dicoba dalam waktu singkat	Minta customer menunggu dan mencoba lagi nanti, atau menghubungi bank mereka terkait limit
`CUSTOMER_CANCELLED`	Soft	Ya	Customer membatalkan transaksi	Biarkan customer memulai ulang checkout saat mereka siap
`DO_NOT_HONOR`	Hard	Tidak	Bank penerbit secara eksplisit menolak transaksi (kode ISO 8583 05 — do not honor); jaringan pembayaran menganggapnya final	Minta customer menghubungi bank mereka; jangan mencoba kembali dengan kartu yang sama
`EXPIRED_CARD`	Hard	Ya	Masa berlaku kartu telah berakhir	Minta customer menggunakan kartu dengan tanggal kedaluwarsa yang valid
`FRAUDULENT`	Hard	Ya	Transaksi ditandai berpotensi sebagai penipuan	Tampilkan pesan decline umum kepada customer — jangan ungkapkan alasannya. Minta mereka menggunakan kartu lain
`GENERIC_DECLINE`	Soft	Tidak	Transaksi ditolak karena alasan yang tidak ditentukan	Minta customer menghubungi bank mereka atau mencoba kartu lain
`INCORRECT_CVC`	Soft	Ya	Kode CVC yang diberikan salah	Minta customer memasukkan kembali CVC yang benar
`INCORRECT_NUMBER`	Soft	Ya	Nomor kartu dimasukkan secara tidak benar	Minta customer memasukkan kembali nomor kartu yang benar
`INSUFFICIENT_FUNDS`	Soft	Ya	Saldo rekening tidak mencukupi untuk menyelesaikan transaksi	Minta customer menggunakan metode pembayaran lain atau mencoba lagi setelah dana tersedia
`INVALID_ACCOUNT`	Hard	Ya	Detail rekening yang diberikan tidak valid	Minta customer menghubungi bank mereka atau menggunakan kartu lain
`INVALID_AMOUNT`	Soft	Ya	Jumlah transaksi tidak valid	Verifikasi jumlah dan batas pembelian dengan customer
`INVALID_CARD_NUMBER`	Soft	Ya	Format nomor kartu tidak valid	Minta customer memasukkan kembali nomor kartu yang valid
`INVALID_CARD_OWNER`	Soft	Ya	Informasi pemilik kartu tidak valid	Minta customer memperbaiki nama pemegang kartu
`INVALID_CVC`	Soft	Ya	Format CVC tidak valid	Minta customer memasukkan kembali CVC yang valid
`INVALID_EXPIRY_YEAR`	Soft	Ya	Tahun kedaluwarsa kartu tidak valid	Minta customer memasukkan tanggal kedaluwarsa yang valid
`INVALID_PIN`	Soft	Ya	PIN yang diberikan salah	Minta customer memasukkan kembali PIN yang benar
`INVALID_REQUEST`	Soft	Ya	Permintaan transaksi berisi data yang tidak valid	Periksa field permintaan pembayaran dan kirim ulang dengan data yang valid
`INVALID_UPI_ID`	Soft	Ya	UPI ID yang diberikan tidak valid	Minta customer memasukkan UPI ID yang valid
`LIMIT_EXCEEDED`	Soft	Ya	Transaksi melebihi limit kartu atau rekening	Minta customer menghubungi bank mereka terkait limit, atau menggunakan metode lain
`LIVE_MODE_TEST_CARD`	Hard	Ya	Kartu pengujian digunakan dalam live mode	Gunakan kartu sungguhan — mencoba kembali dengan kartu pengujian akan selalu gagal dalam live mode
`LOST_CARD`	Hard	Ya	Kartu dilaporkan hilang	Tampilkan pesan decline umum kepada customer — jangan ungkapkan alasannya. Minta mereka menggunakan kartu lain
`MANDATE_INVALID`	Soft	Ya	Mandat pembayaran tidak valid	Minta customer menyiapkan ulang mandat pembayaran
`MANDATE_REQUIRED`	Soft	Ya	Mandat diperlukan untuk transaksi ini	Siapkan mandat dan minta customer mengotorisasinya sebelum melakukan penagihan
`MANDATE_REQUIRED_SYSTEM`	Hard	Tidak	Sistem memerlukan mandat untuk jenis transaksi ini	Pastikan alur penyiapan mandat selesai sebelum melakukan penagihan
`NETWORK_ERROR`	Soft	Tidak	Terjadi kesalahan jaringan selama transaksi	Bersifat sementara — coba kembali pembayaran setelah jeda singkat
`NETWORK_TIMEOUT`	Soft	Tidak	Permintaan jaringan kehabisan waktu	Bersifat sementara — coba kembali pembayaran setelah jeda singkat
`ORDER_ALREADY_EXISTS`	Soft	Tidak	Pesanan sudah ada untuk transaksi ini (pembuatan pesanan duplikat)	Periksa status pesanan yang sudah ada sebelum mencoba lagi; hubungi support jika masalah berlanjut
`ORDER_CREATION_FAILED`	Soft	Tidak	Gagal membuat pesanan untuk transaksi	Kesalahan sementara/sistem — coba kembali pembayaran; hubungi support jika masalah berlanjut
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hard	Ya	Penyedia metode pembayaran menolak transaksi	Minta customer menghubungi penyedia mereka atau menggunakan metode pembayaran lain
`PAYMENT_METHOD_UNSUPPORTED`	Hard	Ya	Metode pembayaran tidak didukung untuk transaksi ini	Minta customer menggunakan metode pembayaran yang didukung
`PICKUP_CARD`	Hard	Ya	Kartu dilaporkan hilang atau dicuri dan ditandai untuk diambil	Tampilkan pesan decline umum kepada customer — jangan ungkapkan alasannya. Minta mereka menggunakan kartu lain
`PROCESSING_ERROR`	Soft	Tidak	Terjadi kesalahan saat memproses transaksi	Bersifat sementara — coba kembali pembayaran; jika berlanjut, minta customer menghubungi bank mereka
`PROVIDER_UNSUPPORTED`	Hard	Tidak	Penyedia pembayaran tidak mendukung jenis transaksi ini	Minta customer menggunakan metode pembayaran lain
`REENTER_TRANSACTION`	Soft	Ya	Transaksi perlu dimasukkan kembali	Minta customer mencoba kembali pembayaran
`REVOCATION_OF_AUTHORIZATION`	Hard	Ya	Otorisasi untuk transaksi telah dicabut	Minta customer menggunakan metode pembayaran lain
`STOLEN_CARD`	Hard	Ya	Kartu dilaporkan dicuri	Tampilkan pesan decline umum kepada customer — jangan ungkapkan alasannya. Minta mereka menggunakan kartu lain
`SUBSCRIPTION_NOT_ACTIVE`	Hard	Tidak	Langganan tidak aktif, sehingga tagihan berulang tidak dapat diproses	Aktifkan kembali langganan (misalnya dengan memperbarui metode pembayaran) sebelum mencoba melakukan penagihan lagi
`TRANSACTION_NOT_ALLOWED`	Hard	Ya	Transaksi tidak diizinkan untuk kartu atau rekening ini	Minta customer menghubungi bank mereka agar mengizinkan jenis transaksi ini, atau menggunakan kartu lain
`TRANSACTION_NOT_APPROVED`	Hard	Ya	Transaksi tidak disetujui	Minta customer menghubungi bank mereka atau mencoba kartu lain
`TRY_AGAIN_LATER`	Soft	Tidak	Transaksi harus dicoba kembali nanti	Bersifat sementara — coba kembali pembayaran nanti
`UNKNOWN_ERROR`	Soft	Tidak	Terjadi kesalahan yang tidak diketahui	Coba kembali pembayaran; jika berlanjut, hubungi support

Kesalahan User menunjukkan apakah decline pembayaran dapat diselesaikan oleh customer. Jika Yes, customer dapat mengambil tindakan untuk memperbaiki masalah (misalnya, memasukkan detail kartu yang benar). Jika No, decline disebabkan oleh masalah tingkat sistem atau pembatasan bank yang tidak dapat diselesaikan langsung oleh customer.

Kartu juga dapat ditolak ketika risk engine milik bank penerbit menandai pemegang kartu sebagai customer berisiko tinggi — terlepas dari merchant atau detail transaksi. Decline ini biasanya muncul sebagai kode umum seperti DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED, atau FRAUDULENT. Dalam kasus ini, bank tidak membagikan alasan spesifiknya, dan Dodo Payments maupun merchant tidak dapat membatalkan keputusan tersebut. Minta customer menghubungi bank mereka untuk menyelesaikan penandaan ini, atau menggunakan kartu maupun metode pembayaran lain.

Menangani Kegagalan Secara Terprogram

Baca error_code dari webhook payment.failed atau objek pembayaran, petakan ke tindakan yang direkomendasikan di atas, lalu tentukan apakah perlu mencoba kembali. Untuk perpanjangan langganan, soft decline otomatis dicoba kembali untuk Anda — lihat Subscription Payment Retries. Untuk error tingkat API dan logika bisnis (seperti PAYMENT_NOT_SUCCEEDED atau REFUND_WINDOW_EXPIRED) yang bukan merupakan card decline, lihat referensi Error Codes.

Terkait

Handle Payment Failures

Panduan menyeluruh untuk mendeteksi, menampilkan, dan mencoba kembali pembayaran yang gagal.

Error Codes

Kode error API dan logika bisnis untuk kegagalan selain decline.

Subscription Payment Retries

Percobaan ulang otomatis yang memulihkan soft decline pada perpanjangan langganan.

Subscription Dunning

Rangkaian email yang memulihkan hard decline dengan meminta pembaruan metode pembayaran.

Dukungan

Untuk bantuan tambahan terkait kegagalan transaksi atau masalah integrasi, silakan hubungi tim support kami di support@dodopayments.com.

API Reference

Checkout Sessions

Payments

Subscriptions

Discounts

Licenses

Entitlements

Customers

Customer Wallets

Products

Localized Pricing

Addons

Credit Entitlements

Meters

Usage Events

Refunds

Disputes

Payouts

Balance Ledger

Brands

Webhooks

Miscellaneous

Product Collections

Ikhtisar

Teks untuk Merchant vs. Teks untuk Customer

Handle Payment Failures

Soft Decline vs. Hard Decline

Alasan Kegagalan Transaksi

Menangani Kegagalan Secara Terprogram

Terkait

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Dukungan

​Ikhtisar

​Teks untuk Merchant vs. Teks untuk Customer

Handle Payment Failures

​Soft Decline vs. Hard Decline

​Alasan Kegagalan Transaksi

​Menangani Kegagalan Secara Terprogram

​Terkait

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Dukungan

Ikhtisar

Teks untuk Merchant vs. Teks untuk Customer

Soft Decline vs. Hard Decline

Alasan Kegagalan Transaksi

Menangani Kegagalan Secara Terprogram

Terkait

Dukungan