Tổng Quan
Khi một lần thử thanh toán thất bại, Dodo Payments trả về một mã lỗi tiêu chuẩn cho biết nguyên nhân. Các mã này giống nhau trên mọi phương thức thanh toán và payment processor, vì vậy một bộ quy tắc xử lý có thể áp dụng cho mọi khoản thanh toán thất bại. Webhookpayment.failed và payment object cung cấp các trường sau cho một khoản thanh toán thất bại:
error_code: mã lỗi tiêu chuẩn từ bảng bên dưới.error_message: giải thích được viết cho bạn, merchant. Khierror_codelà một trong các mã tiêu chuẩn bên dưới, đây là tiêu đề kèm hành động được đề xuất, không phải văn bản thô từ payment processor.retry_attempt:0cho khoản charge ban đầu và1trở lên cho mỗi lần thử lại gia hạn subscription theo lịch. Các khoản thanh toán không phải là gia hạn subscription giữ giá trị0.
Nội dung dành cho Merchant và Customer
Mỗi mã lỗi tiêu chuẩn tương ứng với hai thông báo, một dành cho bạn và một dành cho khách hàng:Customer Portal trả về nội dung dành cho khách hàng trong
error_message, còn merchant API trả về nội dung dành cho merchant cho cùng một payment. error_code giống nhau trong cả hai trường hợp.Handle Payment Failures
Hướng dẫn dành cho developer theo từng bước về cách đọc các mã này từ webhook và API, hiển thị chúng cho khách hàng và quyết định thời điểm thử lại.
Từ chối mềm và từ chối cứng
Mỗi mã lỗi thuộc một trong hai loại: soft decline hoặc hard decline. Loại lỗi cho biết liệu một lần thử sau với cùng thông tin thanh toán có thể thành công hay không, hoặc khách hàng phải thực hiện hành động trước.
Đối với các lần gia hạn subscription, Dodo Payments tự động áp dụng phân loại này. Subscription Payment Retries sẽ thử lại các soft decline. Hard decline sẽ lập tức kết thúc chuỗi thử lại; hãy khôi phục bằng Subscription Dunning.
Lý do giao dịch thất bại
Bảng sau liệt kê mọi mã lỗi cùng với loại decline, việc khách hàng có thể tự giải quyết hay không, mô tả và hành động được đề xuất.User Error cho biết khách hàng có thể tự giải quyết decline hay không.
Yes có nghĩa là khách hàng có thể khắc phục vấn đề, ví dụ bằng cách nhập đúng thông tin thẻ. No có nghĩa là decline do vấn đề cấp hệ thống hoặc hạn chế từ ngân hàng gây ra và khách hàng không thể tự giải quyết trực tiếp.Ngân hàng phát hành cũng có thể từ chối thẻ vì hệ thống đánh giá rủi ro của chính ngân hàng gắn cờ chủ thẻ là có rủi ro cao, không phụ thuộc vào người bán hay thông tin giao dịch. Những lần từ chối này thường hiển thị dưới dạng các mã chung như
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED hoặc FRAUDULENT. Ngân hàng không chia sẻ lý do cụ thể, và cả Dodo Payments lẫn người bán đều không thể ghi đè quyết định này. Hãy yêu cầu khách hàng liên hệ với ngân hàng để xử lý cờ cảnh báo hoặc sử dụng thẻ hay phương thức thanh toán khác.Xử lý lỗi bằng chương trình
Đọcerror_code từ webhook payment.failed hoặc payment object, đối chiếu mã này với hành động được đề xuất trong bảng và quyết định có thử lại hay không. Đối với các lần gia hạn subscription, Dodo Payments sẽ thử lại soft decline thay cho bạn. Xem Subscription Payment Retries.
Đối với các lỗi API và lỗi business logic không phải là card decline, chẳng hạn như PAYMENT_NOT_SUCCEEDED hoặc REFUND_WINDOW_EXPIRED, hãy xem tài liệu tham khảo Error Codes.
Liên quan
Handle Payment Failures
Hướng dẫn end-to-end về cách phát hiện, hiển thị và thử lại các payment thất bại.
Error Codes
Mã lỗi API và lỗi logic nghiệp vụ cho các lỗi không phải từ chối.
Subscription Payment Retries
Tự động thử lại để khắc phục các trường hợp từ chối mềm trong quá trình gia hạn subscription.
Subscription Dunning
Các chuỗi email khắc phục trường hợp từ chối cứng bằng cách nhắc cập nhật payment method.