> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kegagalan Transaksi

> Pahami setiap kode kegagalan transaksi Dodo Payments, apakah itu soft atau hard decline, dan tindakan yang direkomendasikan untuk memulihkan pembayaran.

## 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](/features/recovery/payment-retries), sedangkan hard declines mengakhiri rantai percobaan ulang segera dan sebaiknya ditangani dengan [Subscription Dunning](/features/recovery/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](/features/recovery/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](/api-reference/error-codes).

## Related

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](mailto:support@dodopayments.com).

Untuk bantuan tambahan terkait kegagalan transaksi atau masalah integrasi, silakan hubungi tim dukungan kami di [support@dodopayments.com](mailto:support@dodopayments.com).