Tăng số tiền ủy quyền (increment authorization)

Một số luồng chỉ biết được số tiền cuối cùng sau khi thẻ đã được ủy quyền: một kỳ lưu trú khách sạn kéo dài hơn dự kiến, một lần đổ thêm xăng hoặc gia hạn thuê xe, một đơn hàng có thêm sản phẩm sau khi checkout. Ủy quyền tăng dần (incremental authorization) nâng số tiền đã ủy quyền trên một PaymentIntent đã được xác nhận nhưng chưa capture, để bạn có thể capture nhiều hơn số tiền đã giữ ban đầu.

Điều kiện tiên quyết

Việc tăng số tiền chỉ khả thi nếu thanh toán đã được thiết lập cho việc này từ trước. Tính đủ điều kiện được quyết định tại thời điểm ủy quyền và không thể thêm vào sau đó — không có cách nào để biến một thanh toán đã được ủy quyền thành có thể tăng số tiền.

Yêu cầu	Chi tiết
Manual capture	PaymentIntent phải ở trạng thái requires_capture với capture_method: manual, và charge của nó đã được ủy quyền nhưng chưa capture. Xem Manual capture.
Đã đăng ký từ trước	payment_method_options.card.request_incremental_authorization phải được đặt thành if_available khi PaymentIntent được tạo hoặc xác nhận.
Thẻ, card-not-present	Chỉ áp dụng cho thanh toán thẻ. card_present, napas_qr, và cake_pay không được hỗ trợ.
Trong giới hạn	Tối đa 10 lần tăng cho mỗi charge. Các lệnh gọi tiếp theo sẽ bị từ chối khi đạt giới hạn.

Đăng ký: request_incremental_authorization

Đặt tùy chọn này dưới payment_method_options.card trên lệnh gọi tạo hoặc xác nhận PaymentIntent.

Giá trị	Hành vi
if_available	Yêu cầu ủy quyền tăng dần. Việc có thực sự được cấp hay không do ngân hàng phát hành quyết định tại thời điểm ủy quyền.
never	Mặc định. Không thể tăng số tiền.
request_incremental_authorization_unspecified	Được coi như chưa đặt — có hiệu lực giống never.

Vì tính đủ điều kiện được quyết định tại thời điểm ủy quyền, if_available là một yêu cầu, không phải một sự đảm bảo. Hãy đặt giá trị này bất cứ khi nào việc tăng số tiền là khả dĩ; nó không tốn gì nếu bạn không bao giờ tăng số tiền.

POST /api/payment_intents

{
  "amount": 100000,
  "currency": "704",
  "capture_method": "manual",
  "payment_method_options": {
    "card": {
      "request_incremental_authorization": "if_available"
    }
  }
}

Trường	Bắt buộc	Mô tả
capture_method	Có	Phải là "manual". Việc tăng số tiền không có ý nghĩa với một thanh toán được tự động capture.
payment_method_options.card.request_incremental_authorization	Có	Đặt thành "if_available". Mặc định là "never".

Tăng số tiền

POST /api/payment_intents/{id}/increment_authorization

Request

{
  "amount": 150000,
  "description": "Extended stay — 1 additional night"
}

Trường	Bắt buộc	Mô tả
amount	Có	Tổng số tiền mới đã ủy quyền theo đơn vị tiền tệ nhỏ nhất — không phải phần chênh lệch. Phải lớn hơn amount hiện tại của PaymentIntent.
description	Không	Thay thế description của PaymentIntent. Bỏ qua để giữ nguyên.
metadata	Không	Thay thế metadata của PaymentIntent. Bỏ qua để giữ nguyên.

WARNING

amount là tổng số mới, không phải phần tăng thêm. Để tăng một ủy quyền 100.000 lên thêm 50.000, hãy gửi 150000 — gửi 50000 sẽ bị từ chối vì thấp hơn số tiền hiện tại.

description và metadata thay thế giá trị hiện tại, và chỉ khi có mặt trong request. Chỉ gửi amount sẽ không xóa cả hai trường này.

Response

{
  "payment_intent": {
    "id": "pi_01HZ3X9YQ7M8KH8M5JYV9X4F2B",
    "amount": 150000,
    "amount_capturable": 150000,
    "amount_received": 0,
    "status": "requires_capture"
  }
}

Khi thành công, cả amount và amount_capturable đều tăng theo phần chênh lệch, và amount_received không thay đổi. PaymentIntent vẫn giữ trạng thái requires_capture — việc tăng số tiền chỉ thay đổi số tiền, không thay đổi trạng thái — vì vậy không có webhook trạng thái mới nào cần chờ. Capture tổng số tiền đã tăng như bình thường bằng CapturePaymentIntent.

Ví dụ minh họa

Một khách sạn ủy quyền trước một đêm, khách gia hạn thêm một đêm, và toàn bộ kỳ lưu trú được capture khi checkout.

Bước	Lệnh gọi	amount	amount_capturable	amount_received	Trạng thái
Check-in	Tạo + xác nhận với request_incremental_authorization: if_available, capture_method: manual	100000	100000	0	requires_capture
Khách gia hạn	increment_authorization với { "amount": 150000 }	150000	150000	0	requires_capture
Checkout	capture với {} (toàn bộ, cuối cùng)	150000	0	150000	succeeded

Việc capture ở đây là bình thường — không có gì đặc thù cho việc tăng số tiền. Nếu hóa đơn cuối cùng của khách thấp hơn tổng số đã tăng, hãy capture số tiền thấp hơn với final_capture: true và phần còn lại sẽ được giải phóng. Xem Capture một phần và capture cuối cùng.

Lỗi

Request bị từ chối	Lý do
amount bằng hoặc thấp hơn amount hiện tại	amount là tổng số mới, không phải phần chênh lệch, và phải tăng lên.
PaymentIntent không ở trạng thái requires_capture, hoặc charge của nó đã được capture	Không có ủy quyền còn hiệu lực nào để tăng.
capture_method không phải manual	Việc tăng số tiền chỉ áp dụng cho luồng manual-capture.
request_incremental_authorization không phải if_available khi tạo hoặc xác nhận	Tính đủ điều kiện được quyết định tại thời điểm ủy quyền và không thể thêm vào sau đó. Hãy bắt đầu một thanh toán mới với tùy chọn này được đặt sẵn.
Phương thức thanh toán là card_present, napas_qr, hoặc cake_pay	Chỉ áp dụng cho thanh toán thẻ (card-not-present).
Lần tăng thứ 11 trên cùng một charge	Tối đa 10 lần tăng cho mỗi charge.

Liên quan

• Manual capture — luồng mà tính năng này được xây dựng dựa trên, bao gồm capture một phần và capture cuối cùng
• Kiểm soát 3DS — tùy chọn payment_method_options.card khác