Langsung ke konten utama

​
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 yang distandarisasi dari tabel di bawah.
  • error_message — penjelasan yang dapat dibaca manusia.
  • retry_attempt — 0 untuk biaya asli, 1 atau lebih tinggi untuk setiap percobaan pembaruan langganan berjadwal.
Memahami alasan kegagalan ini memungkinkan Anda memberikan umpan balik yang jelas kepada pelanggan, memutuskan apakah percobaan ulang layak dilakukan, dan memulihkan lebih banyak pendapatan. A step-by-step developer guide for reading these codes from webhooks and the API, surfacing them to customers, and deciding when to retry.

​
Soft vs. Hard Declines

Setiap kode kegagalan masuk ke dalam salah satu dari dua kategori. Perbedaan ini menentukan apakah Anda harus mencoba kembali metode pembayaran yang sama atau meminta pelanggan untuk metode baru.
Decline typeWhat it meansWhat to doExamples
Soft declineSementara atau dapat diperbaiki — kartu yang sama dapat berhasil pada percobaan berikutnya atau setelah pelanggan memperbaiki pengisian mereka.Aman untuk mencoba lagi (setelah jeda, atau setelah pelanggan memperbaiki detailnya).INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER
Hard declineTerminal — mencoba kembali dengan kartu yang sama tidak akan mengubah hasilnya.Jangan mencoba kembali dengan kartu yang sama. Minta pelanggan menggunakan metode pembayaran lain atau hubungi bank mereka.STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT
Untuk pembaharuan langganan, Dodo Payments menerapkan perbedaan ini secara otomatis: soft declines dicoba ulang oleh Subscription Payment Retries, sedangkan hard declines mengakhiri rantai percobaan ulang segera dan sebaiknya ditangani dengan Subscription Dunning. Never reveal the real reason for STOLEN_CARD, LOST_CARD, PICKUP_CARD, or FRAUDULENT to the customer. Surfacing these can tip off a fraudulent actor. Always show the customer a generic decline message (for example, “Your card was declined. Please contact your bank or use another card.”) and only log the specific code internally.

​
Transaction Failure Reasons

Tabel berikut daftar setiap kode kegagalan, jenis penolakan, apakah pelanggan dapat menyelesaikannya, deskripsi, dan tindakan yang direkomendasikan.
Failure CodeTypeUser ErrorDescriptionRecommended Action
AUTHENTICATION_FAILURESoftYesAuthentication failed during the transactionAsk the customer to retry and complete 3DS authentication, or use another card
AUTHENTICATION_REQUIREDSoftYesAdditional authentication is needed to complete the transactionPrompt the customer to complete 3DS authentication. For subscription renewals, ask the customer to return and authenticate
AUTHENTICATION_TIMEOUTSoftYesThe authentication process timed outAsk the customer to retry and complete authentication promptly
CARD_DECLINEDSoftNoThe card was declined by the issuing bank without a specific reason (generic decline)Ask the customer to retry, contact their bank, or use another card
CARD_NOT_ACTIVATEDSoftYesThe card has not been activated by the cardholderAsk the customer to activate the card with their bank, then retry
CARD_VELOCITY_EXCEEDEDSoftYesToo many transactions attempted in a short periodAsk the customer to wait and retry later, or contact their bank about limits
CUSTOMER_CANCELLEDSoftYesThe customer cancelled the transactionLet the customer restart checkout when they are ready
DO_NOT_HONORHardNoThe issuing bank explicitly refused the transaction (ISO 8583 code 05 — do not honor); networks treat this as terminalAsk the customer to contact their bank; do not retry the same card
EXPIRED_CARDHardYesThe card has expiredAsk the customer to use a card with a valid expiry date
FRAUDULENTHardYesThe transaction was flagged as potentially fraudulentShow the customer a generic decline message — do not reveal the reason. Ask them to use another card
GENERIC_DECLINESoftNoThe transaction was declined for an unspecified reasonAsk the customer to contact their bank or try another card
INCORRECT_CVCSoftYesThe provided CVC code was incorrectAsk the customer to re-enter the correct CVC
INCORRECT_NUMBERSoftYesThe card number was entered incorrectlyAsk the customer to re-enter the correct card number
INSUFFICIENT_FUNDSSoftYesThe account has insufficient funds to complete the transactionAsk the customer to use another payment method or retry once funds are available
INVALID_ACCOUNTHardYesThe account details provided are invalidAsk the customer to contact their bank or use another card
INVALID_AMOUNTSoftYesThe transaction amount is invalidVerify the amount and any purchase limits with the customer
INVALID_CARD_NUMBERSoftYesThe card number format is invalidAsk the customer to re-enter a valid card number
INVALID_CARD_OWNERSoftYesThe card owner information is invalidAsk the customer to correct the cardholder name
INVALID_CVCSoftYesThe CVC format is invalidAsk the customer to re-enter a valid CVC
INVALID_EXPIRY_YEARSoftYesThe card expiry year is invalidAsk the customer to enter a valid expiry date
INVALID_PINSoftYesThe provided PIN is incorrectAsk the customer to re-enter the correct PIN
INVALID_REQUESTSoftYesThe transaction request contains invalid dataCheck the payment request fields and resubmit with valid data
INVALID_UPI_IDSoftYesThe UPI ID provided is invalidAsk the customer to enter a valid UPI ID
LIMIT_EXCEEDEDSoftYesThe transaction exceeds the card or account limitAsk the customer to contact their bank about limits, or use another method
LIVE_MODE_TEST_CARDHardYesA test card was used in live modeUse a real card — retrying the test card will always fail in live mode
LOST_CARDHardYesThe card has been reported as lostShow the customer a generic decline message — do not reveal the reason. Ask them to use another card
MANDATE_INVALIDSoftYesThe payment mandate is invalidAsk the customer to set up the payment mandate again
MANDATE_REQUIREDSoftYesA mandate is required for this transactionSet up a mandate and ask the customer to authorize it before charging
MANDATE_REQUIRED_SYSTEMHardNoThe system requires a mandate for this transaction typeEnsure the mandate setup flow is completed before charging
NETWORK_ERRORSoftNoA network error occurred during the transactionTransient — retry the payment after a short delay
NETWORK_TIMEOUTSoftNoThe network request timed outTransient — retry the payment after a short delay
ORDER_ALREADY_EXISTSSoftNoAn order already exists for this transaction (duplicate order creation)Check the status of the existing order before retrying; contact support if it persists
ORDER_CREATION_FAILEDSoftNoFailed to create the order for the transactionTransient/system error — retry the payment; contact support if it persists
PAYMENT_METHOD_PROVIDER_DECLINEDHardYesThe payment method provider declined the transactionAsk the customer to contact their provider or use another payment method
PAYMENT_METHOD_UNSUPPORTEDHardYesThe payment method is not supported for this transactionAsk the customer to use a supported payment method
PICKUP_CARDHardYesThe card has been reported as lost or stolen and flagged for pickupShow the customer a generic decline message — do not reveal the reason. Ask them to use another card
PROCESSING_ERRORSoftNoAn error occurred while processing the transactionTransient — retry the payment; if it persists, ask the customer to contact their bank
PROVIDER_UNSUPPORTEDHardNoThe payment provider does not support this transaction typeAsk the customer to use another payment method
REENTER_TRANSACTIONSoftYesThe transaction needs to be re-enteredAsk the customer to retry the payment
REVOCATION_OF_AUTHORIZATIONHardYesThe authorization for the transaction was revokedAsk the customer to use another payment method
STOLEN_CARDHardYesThe card has been reported as stolenShow the customer a generic decline message — do not reveal the reason. Ask them to use another card
SUBSCRIPTION_NOT_ACTIVEHardNoThe subscription is not active, so the recurring charge could not be processedReactivate the subscription (for example, by updating the payment method) before attempting the charge again
TRANSACTION_NOT_ALLOWEDHardYesThe transaction is not allowed for this card or accountAsk the customer to contact their bank to allow this transaction type, or use another card
TRANSACTION_NOT_APPROVEDHardYesThe transaction was not approvedAsk the customer to contact their bank or try another card
TRY_AGAIN_LATERSoftNoThe transaction should be retried laterTransient — retry the payment later
UNKNOWN_ERRORSoftNoAn unknown error occurredRetry the payment; if it persists, contact support
User Error menunjukkan apakah penolakan pembayaran dapat diselesaikan oleh pelanggan. Ketika Yes, pelanggan dapat mengambil tindakan untuk memperbaiki masalah (misalnya, memasukkan detail kartu yang benar). Ketika No, penolakan disebabkan oleh masalah di tingkat sistem atau pembatasan bank yang tidak dapat diselesaikan langsung oleh pelanggan.

​
Handling Failures Programmatically

Baca error_code dari webhook payment.failed atau objek pembayaran, memetakan ke tindakan yang direkomendasikan di atas, dan memutuskan apakah akan mencoba kembali. Untuk pembaruan langganan, soft declines secara otomatis dicoba ulang untuk Anda — lihat Subscription Payment Retries. Untuk kesalahan tingkat API dan logika bisnis (seperti PAYMENT_NOT_SUCCEEDED atau REFUND_WINDOW_EXPIRED) yang bukan penolakan kartu, lihat referensi Error Codes. End-to-end guide to detecting, surfacing, and retrying failed payments. API and business-logic error codes for non-decline failures. Automatic retries that recover soft declines on subscription renewals. Email sequences that recover hard declines by prompting a payment method update.

​
Support

Untuk bantuan lebih lanjut dengan kegagalan transaksi atau masalah integrasi, silakan hubungi tim dukungan kami di support@dodopayments.com.
Terakhir diubah pada 18 Juni 2026