Kegagalan Transaksi - Dodo Payments Documentation

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 type	What it means	What to do	Examples
Soft decline	Sementara 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 decline	Terminal — 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 Code	Type	User Error	Description	Recommended Action
`AUTHENTICATION_FAILURE`	Soft	Yes	Authentication failed during the transaction	Ask the customer to retry and complete 3DS authentication, or use another card
`AUTHENTICATION_REQUIRED`	Soft	Yes	Additional authentication is needed to complete the transaction	Prompt the customer to complete 3DS authentication. For subscription renewals, ask the customer to return and authenticate
`AUTHENTICATION_TIMEOUT`	Soft	Yes	The authentication process timed out	Ask the customer to retry and complete authentication promptly
`CARD_DECLINED`	Soft	No	The 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_ACTIVATED`	Soft	Yes	The card has not been activated by the cardholder	Ask the customer to activate the card with their bank, then retry
`CARD_VELOCITY_EXCEEDED`	Soft	Yes	Too many transactions attempted in a short period	Ask the customer to wait and retry later, or contact their bank about limits
`CUSTOMER_CANCELLED`	Soft	Yes	The customer cancelled the transaction	Let the customer restart checkout when they are ready
`DO_NOT_HONOR`	Hard	No	The issuing bank explicitly refused the transaction (ISO 8583 code 05 — do not honor); networks treat this as terminal	Ask the customer to contact their bank; do not retry the same card
`EXPIRED_CARD`	Hard	Yes	The card has expired	Ask the customer to use a card with a valid expiry date
`FRAUDULENT`	Hard	Yes	The transaction was flagged as potentially fraudulent	Show the customer a generic decline message — do not reveal the reason. Ask them to use another card
`GENERIC_DECLINE`	Soft	No	The transaction was declined for an unspecified reason	Ask the customer to contact their bank or try another card
`INCORRECT_CVC`	Soft	Yes	The provided CVC code was incorrect	Ask the customer to re-enter the correct CVC
`INCORRECT_NUMBER`	Soft	Yes	The card number was entered incorrectly	Ask the customer to re-enter the correct card number
`INSUFFICIENT_FUNDS`	Soft	Yes	The account has insufficient funds to complete the transaction	Ask the customer to use another payment method or retry once funds are available
`INVALID_ACCOUNT`	Hard	Yes	The account details provided are invalid	Ask the customer to contact their bank or use another card
`INVALID_AMOUNT`	Soft	Yes	The transaction amount is invalid	Verify the amount and any purchase limits with the customer
`INVALID_CARD_NUMBER`	Soft	Yes	The card number format is invalid	Ask the customer to re-enter a valid card number
`INVALID_CARD_OWNER`	Soft	Yes	The card owner information is invalid	Ask the customer to correct the cardholder name
`INVALID_CVC`	Soft	Yes	The CVC format is invalid	Ask the customer to re-enter a valid CVC
`INVALID_EXPIRY_YEAR`	Soft	Yes	The card expiry year is invalid	Ask the customer to enter a valid expiry date
`INVALID_PIN`	Soft	Yes	The provided PIN is incorrect	Ask the customer to re-enter the correct PIN
`INVALID_REQUEST`	Soft	Yes	The transaction request contains invalid data	Check the payment request fields and resubmit with valid data
`INVALID_UPI_ID`	Soft	Yes	The UPI ID provided is invalid	Ask the customer to enter a valid UPI ID
`LIMIT_EXCEEDED`	Soft	Yes	The transaction exceeds the card or account limit	Ask the customer to contact their bank about limits, or use another method
`LIVE_MODE_TEST_CARD`	Hard	Yes	A test card was used in live mode	Use a real card — retrying the test card will always fail in live mode
`LOST_CARD`	Hard	Yes	The card has been reported as lost	Show the customer a generic decline message — do not reveal the reason. Ask them to use another card
`MANDATE_INVALID`	Soft	Yes	The payment mandate is invalid	Ask the customer to set up the payment mandate again
`MANDATE_REQUIRED`	Soft	Yes	A mandate is required for this transaction	Set up a mandate and ask the customer to authorize it before charging
`MANDATE_REQUIRED_SYSTEM`	Hard	No	The system requires a mandate for this transaction type	Ensure the mandate setup flow is completed before charging
`NETWORK_ERROR`	Soft	No	A network error occurred during the transaction	Transient — retry the payment after a short delay
`NETWORK_TIMEOUT`	Soft	No	The network request timed out	Transient — retry the payment after a short delay
`ORDER_ALREADY_EXISTS`	Soft	No	An 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_FAILED`	Soft	No	Failed to create the order for the transaction	Transient/system error — retry the payment; contact support if it persists
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hard	Yes	The payment method provider declined the transaction	Ask the customer to contact their provider or use another payment method
`PAYMENT_METHOD_UNSUPPORTED`	Hard	Yes	The payment method is not supported for this transaction	Ask the customer to use a supported payment method
`PICKUP_CARD`	Hard	Yes	The card has been reported as lost or stolen and flagged for pickup	Show the customer a generic decline message — do not reveal the reason. Ask them to use another card
`PROCESSING_ERROR`	Soft	No	An error occurred while processing the transaction	Transient — retry the payment; if it persists, ask the customer to contact their bank
`PROVIDER_UNSUPPORTED`	Hard	No	The payment provider does not support this transaction type	Ask the customer to use another payment method
`REENTER_TRANSACTION`	Soft	Yes	The transaction needs to be re-entered	Ask the customer to retry the payment
`REVOCATION_OF_AUTHORIZATION`	Hard	Yes	The authorization for the transaction was revoked	Ask the customer to use another payment method
`STOLEN_CARD`	Hard	Yes	The card has been reported as stolen	Show the customer a generic decline message — do not reveal the reason. Ask them to use another card
`SUBSCRIPTION_NOT_ACTIVE`	Hard	No	The subscription is not active, so the recurring charge could not be processed	Reactivate the subscription (for example, by updating the payment method) before attempting the charge again
`TRANSACTION_NOT_ALLOWED`	Hard	Yes	The transaction is not allowed for this card or account	Ask the customer to contact their bank to allow this transaction type, or use another card
`TRANSACTION_NOT_APPROVED`	Hard	Yes	The transaction was not approved	Ask the customer to contact their bank or try another card
`TRY_AGAIN_LATER`	Soft	No	The transaction should be retried later	Transient — retry the payment later
`UNKNOWN_ERROR`	Soft	No	An unknown error occurred	Retry 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. Untuk bantuan tambahan terkait kegagalan transaksi atau masalah integrasi, silakan hubungi tim dukungan kami di support@dodopayments.com.

​Ikhtisar

​Soft vs. Hard Declines

​Transaction Failure Reasons

​Handling Failures Programmatically

​Related

​Support

Ikhtisar

Soft vs. Hard Declines

Transaction Failure Reasons

Handling Failures Programmatically

Related

Support