Mã lỗi
Khi API trả về lỗi, response body chứa một đối tượng JSON với các trường code, type, và message.
{
"code": "card_declined",
"type": "card_error",
"message": "Your card was declined."
}Với card_declined, trường decline_code (mã từ chối do ngân hàng phát hành thẻ trả về) cũng có mặt.
Các loại lỗi
| Type | Mô tả |
|---|---|
api_error | Lỗi nội bộ đã xảy ra ở phía chúng tôi. Thử lại request. |
authentication_error | Xác thực với API thất bại. Kiểm tra API key hoặc chữ ký JWS của bạn. |
invalid_request_error | Request có tham số không hợp lệ hoặc thiếu trường bắt buộc. |
card_error | Thẻ bị từ chối hoặc không vượt qua kiểm tra hợp lệ. |
rate_limit_error | Quá nhiều request. Giảm tần suất và thử lại. |
idempotency_error | Idempotency key đã được dùng với các tham số request khác nhau. |
Mã trạng thái HTTP
| Status | Ý nghĩa |
|---|---|
200 | Thành công. |
400 | Bad Request. Tham số không hợp lệ hoặc thiếu trường bắt buộc. |
401 | Unauthorized. Thông tin xác thực không hợp lệ hoặc bị thiếu. |
403 | Forbidden. Request không được phép. |
404 | Not Found. Resource yêu cầu không tồn tại. |
409 | Conflict. Resource đang ở trạng thái xung đột với request. |
429 | Too Many Requests. Đã vượt giới hạn tốc độ. |
500 | Internal Server Error. Có sự cố ở phía chúng tôi. |
Lỗi thanh toán
amount_too_large
Số tiền tính phí vượt quá giới hạn tối đa cho phép.
amount_too_small
Số tiền tính phí thấp hơn giới hạn tối thiểu cho phép.
authentication_required
Thanh toán cần thêm bước xác thực từ khách hàng (ví dụ 3D Secure).
balance_insufficient
Tài khoản không đủ số dư cho khoản chuyển hoặc chi trả yêu cầu.
Lỗi thẻ
card_declined
Thẻ đã bị từ chối. Kiểm tra trường decline_code để biết lý do cụ thể.
Các mã từ chối thường gặp:
| Decline Code | Mô tả |
|---|---|
insufficient_funds | Thẻ không đủ số dư để hoàn tất thanh toán. |
lost_card | Thẻ đã được báo mất. |
stolen_card | Thẻ đã được báo bị đánh cắp. |
generic_decline | Thẻ bị từ chối với lý do không xác định. |
do_not_honor | Ngân hàng phát hành thẻ đã từ chối giao dịch. |
transaction_not_allowed | Thẻ không hỗ trợ loại giao dịch này. |
expired_card
Thẻ đã hết hạn. Yêu cầu khách hàng sử dụng thẻ khác.
incorrect_cvc
Mã bảo mật của thẻ (CVC/CVV) không đúng.
incorrect_number
Số thẻ không đúng.
invalid_cvc
Mã bảo mật của thẻ không hợp lệ (sai định dạng hoặc độ dài).
invalid_expiry_month
Tháng hết hạn của thẻ không đúng.
invalid_expiry_year
Năm hết hạn của thẻ không đúng.
invalid_number
Số thẻ không phải là một số thẻ tín dụng hợp lệ.
processing_error
Đã xảy ra lỗi khi xử lý thẻ. Thử lại thanh toán.
Lỗi Payment Intent
payment_intent_unexpected_state
Payment intent đang ở trạng thái không cho phép thực hiện thao tác yêu cầu. Ví dụ, thử xác nhận một payment intent đã ở trạng thái succeeded.
payment_intent_authentication_failure
Phương thức thanh toán không vượt qua xác thực (ví dụ thử thách 3D Secure thất bại).
payment_intent_invalid_parameter
Một hoặc nhiều tham số được cung cấp cho payment intent không hợp lệ.
payment_intent_payment_attempt_expired
Lần thử thanh toán gần nhất đã hết hạn. Tạo một payment intent mới hoặc thử lại.
payment_intent_payment_attempt_failed
Lần thử thanh toán gần nhất thất bại. Kiểm tra last_payment_error để biết chi tiết.
Lỗi Payment Method
payment_method_not_available
Bộ xử lý cho phương thức thanh toán này tạm thời không sẵn có. Thử lại sau.
payment_method_currency_mismatch
Tiền tệ không khớp với các tiền tệ mà phương thức thanh toán hỗ trợ.
payment_method_unactivated
Phương thức thanh toán chưa được kích hoạt. Liên hệ bộ phận hỗ trợ.
payment_method_provider_decline
Thanh toán hoặc setup đã bị ngân hàng phát hành thẻ hoặc nhà cung cấp từ chối.
payment_method_provider_timeout
Phương thức thanh toán thất bại do timeout với nhà cung cấp.
Lỗi 3D Secure
three_d_secure_authentication_failed
Thử thách xác thực 3D Secure không được hoàn tất thành công.
three_d_secure_not_supported
Thẻ hoặc ngân hàng phát hành thẻ không hỗ trợ xác thực 3D Secure.
three_d_secure_action_expired
Hành động xác thực 3D Secure đã hết hạn. Thử lại thanh toán.
three_d_secure_invalid_cryptogram
Cryptogram 3D Secure được cung cấp không hợp lệ hoặc đã được sử dụng.
Lỗi hoàn tiền
charge_already_refunded
Charge đã được hoàn tiền đầy đủ.
charge_disputed
Charge đang trong tranh chấp và không thể hoàn tiền. Chờ tranh chấp được giải quyết.
refund_amount_exceeds_charge
Số tiền hoàn vượt quá số tiền charge ban đầu trừ đi các khoản hoàn tiền trước đó.
Lỗi request
parameter_missing
Một hoặc nhiều tham số bắt buộc bị thiếu trong request.
parameter_invalid_empty
Một tham số bắt buộc được cung cấp nhưng rỗng.
parameter_unknown
Request chứa một hoặc nhiều tham số không xác định.
parameters_exclusive
Hai hoặc nhiều tham số loại trừ lẫn nhau được cung cấp cùng lúc. Ví dụ, cả payment_method_id và confirmation_token trong một request confirm.
resource_missing
Resource được yêu cầu không tồn tại. Kiểm tra lại ID.
idempotency_key_in_use
Idempotency key đang được sử dụng bởi một request khác đang xử lý.
Lỗi xác thực
api_key_expired
API key đã hết hạn. Tạo key mới.
api_key_invalid
API key được cung cấp không hợp lệ hoặc sai định dạng.
jws_signature_invalid
Xác minh chữ ký JWS thất bại. Kiểm tra khóa ký và thuật toán của bạn.
jws_token_expired
JWS token đã hết hạn. Tạo request đã ký mới.
Giới hạn tốc độ
rate_limit
Quá nhiều request trong một khoảng thời gian ngắn. Áp dụng exponential backoff và thử lại.
Các header giới hạn tốc độ:
| Header | Mô tả |
|---|---|
X-RateLimit-Limit | Số request tối đa cho phép mỗi cửa sổ. |
X-RateLimit-Remaining | Số request còn lại trong cửa sổ hiện tại. |
X-RateLimit-Reset | Timestamp Unix khi giới hạn tốc độ được reset. |