Kegagalan Transaksi

Ikhtisar

Saat upaya pembayaran gagal, Dodo Payments mengembalikan kode kegagalan standar yang menjelaskan alasannya. Kode ini sama di semua metode pembayaran dan payment processor, sehingga satu set aturan penanganan dapat mencakup setiap pembayaran yang gagal. Webhook payment.failed dan payment object menampilkan field berikut untuk pembayaran yang gagal:

error_code: kode kegagalan standar dari tabel di bawah.
error_message: penjelasan yang ditulis untuk Anda, merchant. Saat error_code merupakan salah satu kode standar di bawah, field ini berisi judul utama dan tindakan yang direkomendasikan, bukan teks mentah dari payment processor.
retry_attempt: 0 untuk charge asli, dan 1 atau lebih tinggi untuk setiap percobaan ulang renewal subscription yang dijadwalkan. Pembayaran yang bukan renewal subscription mempertahankan nilai 0.

Gunakan kode ini untuk memberikan feedback yang jelas kepada customer, menentukan apakah retry dapat berhasil, dan memulihkan lebih banyak pendapatan.

Teks untuk Merchant vs. Teks untuk Customer

Setiap kode kegagalan standar dipetakan ke dua pesan, satu untuk Anda dan satu untuk customer Anda:

Audiens	Tempat ditampilkan	Isi pesan
Anda	`error_message` pada payment, halaman detail payment di dashboard, dan email payment-failed yang diterima merchant	Alasan sebenarnya serta tindakan yang direkomendasikan, misalnya “Kartu belum diaktifkan oleh pemegang kartu. Minta customer mengaktifkannya melalui bank mereka, lalu lakukan retry.”
Customer Anda	Layar kegagalan checkout, Customer Portal, dan email dunning	Penjelasan singkat dengan bahasa sederhana yang dapat mereka tindak lanjuti, misalnya “Kartu Anda belum diaktifkan. Silakan aktifkan melalui bank Anda dan coba lagi.”

Customer Portal mengembalikan teks untuk customer dalam error_message, sedangkan merchant API mengembalikan teks untuk merchant untuk payment yang sama. error_code sama 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 melakukan retry.

Soft Decline vs. Hard Decline

Setiap kode kegagalan merupakan soft decline atau hard decline. Jenisnya menunjukkan apakah percobaan berikutnya dengan detail payment yang sama dapat berhasil, atau apakah customer harus melakukan tindakan terlebih dahulu.

Jenis decline	Artinya	Tindakan	Contoh
Soft decline	Sementara. Detail payment yang sama dapat berhasil pada percobaan berikutnya.	Lakukan retry setelah jeda.	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Hard decline	Retry dengan detail payment yang sama tanpa tindakan dari customer tidak akan mengubah hasil.	Jangan melakukan retry dengan detail yang sama. Minta customer memperbaiki detail mereka, menyelesaikan authentication, menghubungi bank mereka, atau menggunakan metode pembayaran lain.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`, `INCORRECT_CVC`

Untuk renewal subscription, Dodo Payments menerapkan klasifikasi ini secara otomatis. Subscription Payment Retries melakukan retry untuk soft decline. Hard decline langsung mengakhiri rangkaian retry; pulihkan dengan Subscription Dunning.

Jangan pernah mengungkapkan alasan sebenarnya untuk STOLEN_CARD, LOST_CARD, PICKUP_CARD, atau FRAUDULENT kepada customer. Mengungkapkan alasan ini dapat memperingatkan pelaku penipuan. 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 menerapkan aturan ini pada surface yang dikontrolnya. Untuk keempat kode ini, checkout, Customer Portal, dan email dunning menampilkan pesan decline umum, sementara teks merchant Anda tetap menyertakan 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 beserta jenis decline, apakah customer dapat mengatasinya, deskripsi, dan tindakan yang direkomendasikan.

Failure Code	Type	User Error	Description	Recommended Action
`AUTHENTICATION_FAILURE`	Hard	Ya	Authentication gagal selama transaksi	Minta customer mencoba lagi dan menyelesaikan authentication 3DS, atau menggunakan kartu lain
`AUTHENTICATION_REQUIRED`	Hard	Ya	Authentication tambahan diperlukan untuk menyelesaikan transaksi	Minta customer menyelesaikan authentication 3DS. Untuk renewal subscription, minta customer kembali dan melakukan authentication
`AUTHENTICATION_TIMEOUT`	Soft	Ya	Proses authentication mengalami timeout	Minta customer mencoba lagi dan segera menyelesaikan authentication
`CARD_DECLINED`	Soft	Tidak	Bank penerbit menolak kartu tanpa alasan spesifik (generic decline)	Minta customer mencoba lagi, menghubungi bank mereka, atau menggunakan kartu lain
`CARD_NOT_ACTIVATED`	Soft	Ya	Pemegang kartu belum mengaktifkan kartu	Minta customer mengaktifkan kartu melalui bank mereka, lalu mencoba lagi
`CARD_VELOCITY_EXCEEDED`	Soft	Ya	Terlalu banyak transaksi dicoba dalam waktu singkat	Minta customer menunggu dan mencoba lagi nanti, atau menghubungi bank mereka mengenai limit
`CUSTOMER_CANCELLED`	Hard	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). Card network menganggapnya terminal	Minta customer menghubungi bank mereka. Jangan melakukan retry dengan kartu yang sama
`EXPIRED_CARD`	Hard	Ya	Kartu telah kedaluwarsa	Minta customer menggunakan kartu dengan tanggal kedaluwarsa yang valid
`FRAUDULENT`	Hard	Ya	Transaksi ditandai sebagai berpotensi fraudulent	Tampilkan pesan decline umum kepada customer tanpa alasannya. Minta mereka menggunakan kartu lain
`GENERIC_DECLINE`	Soft	Tidak	Transaksi ditolak karena alasan yang tidak disebutkan	Minta customer menghubungi bank mereka atau mencoba kartu lain
`INCORRECT_CVC`	Hard	Ya	CVC yang dimasukkan salah	Minta customer memasukkan kembali CVC yang benar
`INCORRECT_NUMBER`	Hard	Ya	Nomor kartu yang dimasukkan salah	Minta customer memasukkan kembali nomor kartu yang benar
`INSUFFICIENT_FUNDS`	Soft	Ya	Akun tidak memiliki dana yang cukup untuk menyelesaikan transaksi	Minta customer menggunakan metode pembayaran lain atau mencoba lagi setelah dana tersedia
`INVALID_ACCOUNT`	Hard	Ya	Detail akun yang diberikan tidak valid	Minta customer menghubungi bank mereka atau menggunakan kartu lain
`INVALID_AMOUNT`	Hard	Ya	Jumlah transaksi tidak valid	Verifikasi jumlah dan limit pembelian dengan customer
`INVALID_CARD_NUMBER`	Hard	Ya	Format nomor kartu tidak valid	Minta customer memasukkan kembali nomor kartu yang valid
`INVALID_CARD_OWNER`	Hard	Ya	Informasi pemilik kartu tidak valid	Minta customer memperbaiki nama pemegang kartu
`INVALID_CVC`	Hard	Ya	Format CVC tidak valid	Minta customer memasukkan kembali CVC yang valid
`INVALID_EXPIRY_YEAR`	Hard	Ya	Tahun kedaluwarsa kartu tidak valid	Minta customer memasukkan tanggal kedaluwarsa yang valid
`INVALID_PIN`	Hard	Ya	PIN yang dimasukkan salah	Minta customer memasukkan kembali PIN yang benar
`INVALID_REQUEST`	Hard	Ya	Permintaan transaksi berisi data yang tidak valid	Periksa field payment request dan kirim ulang dengan data yang valid
`INVALID_UPI_ID`	Hard	Ya	UPI ID yang diberikan tidak valid	Minta customer memasukkan UPI ID yang valid
`LIMIT_EXCEEDED`	Soft	Ya	Transaksi melebihi limit kartu atau akun	Minta customer menghubungi bank mereka mengenai limit, atau menggunakan metode lain
`LIVE_MODE_TEST_CARD`	Hard	Ya	Test card digunakan dalam live mode	Gunakan kartu asli. Test card selalu gagal dalam live mode
`LOST_CARD`	Hard	Ya	Kartu telah dilaporkan hilang	Tampilkan pesan decline umum kepada customer tanpa alasannya. Minta mereka menggunakan kartu lain
`MANDATE_INVALID`	Hard	Ya	Payment mandate tidak valid	Minta customer menyiapkan payment mandate lagi
`MANDATE_REQUIRED`	Hard	Ya	Mandate diperlukan untuk transaksi ini	Siapkan mandate dan minta customer mengotorisasinya sebelum melakukan charge
`MANDATE_REQUIRED_SYSTEM`	Hard	Tidak	Sistem memerlukan mandate untuk jenis transaksi ini	Selesaikan flow penyiapan mandate sebelum melakukan charge
`NETWORK_ERROR`	Soft	Tidak	Terjadi network error selama transaksi	Transient. Lakukan retry payment setelah jeda singkat
`NETWORK_TIMEOUT`	Soft	Tidak	Network request mengalami timeout	Transient. Lakukan retry payment setelah jeda singkat
`ORDER_ALREADY_EXISTS`	Hard	Tidak	Order sudah ada untuk transaksi ini (pembuatan order duplikat)	Periksa status order yang sudah ada sebelum melakukan retry. Hubungi support jika masalah berlanjut
`ORDER_CREATION_FAILED`	Soft	Tidak	Order untuk transaksi tidak dapat dibuat	Error transient atau system error. Lakukan retry payment, dan hubungi support jika masalah berlanjut
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hard	Ya	Payment method provider menolak transaksi	Minta customer menghubungi provider mereka atau menggunakan metode pembayaran lain
`PAYMENT_METHOD_UNSUPPORTED`	Hard	Ya	Payment method tidak didukung untuk transaksi ini	Minta customer menggunakan payment method yang didukung
`PICKUP_CARD`	Hard	Ya	Kartu telah dilaporkan hilang atau dicuri dan ditandai untuk diambil	Tampilkan pesan decline umum kepada customer tanpa alasannya. Minta mereka menggunakan kartu lain
`PROCESSING_ERROR`	Soft	Tidak	Terjadi error saat memproses transaksi	Transient. Lakukan retry payment. Jika berlanjut, minta customer menghubungi bank mereka
`PROVIDER_UNSUPPORTED`	Hard	Tidak	Payment provider tidak mendukung jenis transaksi ini	Minta customer menggunakan metode pembayaran lain
`REENTER_TRANSACTION`	Soft	Ya	Transaksi perlu dimasukkan kembali	Minta customer mencoba kembali payment
`REVOCATION_OF_AUTHORIZATION`	Hard	Ya	Otorisasi untuk transaksi telah dicabut	Minta customer menggunakan metode pembayaran lain
`STOLEN_CARD`	Hard	Ya	Kartu telah dilaporkan dicuri	Tampilkan pesan decline umum kepada customer tanpa alasannya. Minta mereka menggunakan kartu lain
`SUBSCRIPTION_NOT_ACTIVE`	Hard	Tidak	Subscription tidak aktif, sehingga recurring charge tidak dapat diproses	Aktifkan kembali subscription (misalnya dengan memperbarui payment method) sebelum mencoba charge lagi
`TRANSACTION_NOT_ALLOWED`	Soft	Ya	Transaksi tidak diizinkan untuk kartu atau akun ini	Lakukan retry setelah jeda. Jika terus gagal, minta customer menghubungi bank mereka agar mengizinkan jenis transaksi ini, atau menggunakan kartu lain
`TRANSACTION_NOT_APPROVED`	Soft	Ya	Transaksi tidak disetujui	Lakukan retry setelah jeda. Jika terus gagal, minta customer menghubungi bank mereka atau mencoba kartu lain
`TRY_AGAIN_LATER`	Soft	Tidak	Transaksi harus dicoba lagi nanti	Transient. Lakukan retry payment nanti
`UNKNOWN_ERROR`	Soft	Tidak	Terjadi error yang tidak diketahui	Lakukan retry payment. Jika berlanjut, hubungi support

User Error menunjukkan apakah customer dapat mengatasi decline. Yes berarti customer dapat memperbaiki masalah tersebut, misalnya dengan memasukkan detail kartu yang benar. No berarti decline disebabkan oleh masalah tingkat sistem atau pembatasan bank, dan customer tidak dapat mengatasinya secara langsung.

Bank penerbit juga dapat menolak kartu karena mesin risikonya sendiri menandai pemegang kartu sebagai berisiko tinggi, terlepas dari merchant atau detail transaksi. Penolakan ini biasanya muncul sebagai kode umum seperti DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED, atau FRAUDULENT. Bank tidak membagikan alasan spesifiknya, dan Dodo Payments maupun merchant tidak dapat membatalkan keputusan tersebut. Minta pelanggan menghubungi bank mereka untuk menyelesaikan penandaan tersebut, atau menggunakan kartu atau metode pembayaran lain.

Menangani Kegagalan Secara Terprogram

Baca error_code dari webhook payment.failed atau payment object, petakan ke tindakan yang direkomendasikan dalam tabel, lalu tentukan apakah perlu melakukan retry. Untuk renewal subscription, Dodo Payments melakukan retry soft decline untuk Anda. Lihat Subscription Payment Retries. Untuk error API dan business logic yang bukan card decline, seperti PAYMENT_NOT_SUCCEEDED atau REFUND_WINDOW_EXPIRED, 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 lebih lanjut terkait kegagalan transaksi atau masalah integrasi, hubungi tim support 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

Moderation

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