OOB callback

Endpoint duy nhất mà bạn đóng vai trò client. Hãy gọi nó ngay khi chủ thẻ phê duyệt hoặc từ chối một challenge out-of-band trong app của bạn, để trang chờ hoàn tất ngay lập tức thay vì phải đợi họ nhấn Continue.

URL này được gửi cho bạn trên mỗi /initiate_action dạng out-of-band, dưới tên trường OOBCallbackUrl. Hãy dùng giá trị đó thay vì hardcode một đường dẫn cố định.

Tùy chọn, nhưng nên triển khai

Nếu không có callback, luồng vẫn hoàn tất — ACS sẽ chuyển sang poll /validate. Sự khác biệt nằm ở trải nghiệm của chủ thẻ: có callback thì trang hoàn tất ngay khi họ phê duyệt; không có thì không có gì xảy ra cho đến khi họ nhấn Continue.

Request

POST /oob-callback HTTP/1.1
Content-Type: application/json
signature: <base64 HMAC-SHA256 của raw body>

{
  "TransactionId": "9f6b6a2e-6f4e-4d0a-9b6e-2f9d6c1a7e10",
  "StepupRequestId": "b2b6c9a4-1d0e-4e3a-8c8b-5a1f2d3c4b5a",
  "Status": "SUCCESS",
  "Reason": {
    "ReasonCode": "USER_APPROVED",
    "ReasonDescription": "Approved in the app"
  }
}

Trường	Bắt buộc	Mô tả
TransactionId	Có	Giá trị nhận được trong /initiate_action
StepupRequestId	Có	Phải khớp với phiên, nếu không request sẽ bị từ chối
Status	Có	SUCCESS hoặc FAILURE
Reason	Không	Được ghi lại để hỗ trợ điều tra sự cố; không ảnh hưởng đến kết quả

Header signature là bắt buộc trong môi trường production — xem Bảo mật để biết cách tính nó.

Response

HTTP	Status trong body	Khi nào
200	SUCCESS	Đã ghi nhận. Cũng được trả về cho một callback trùng lặp của một kết quả đã final
400	ERROR	Body sai định dạng, Status không hợp lệ, hoặc phiên này không phải out-of-band
401	ERROR	Thiếu signature hoặc signature không hợp lệ
404	ERROR	Không tìm thấy TransactionId, hoặc StepupRequestId không khớp
405	ERROR	Phương thức khác POST
500	ERROR	ACS không thể đọc hoặc lưu kết quả — an toàn để thử lại

Idempotency

Gọi lại nhiều lần là an toàn. Khi một phiên đã final, một callback trùng lặp sẽ bị bỏ qua và vẫn trả về 200 — vì vậy một lần thử lại sau lỗi mạng sẽ không làm hỏng một kết quả đã được ghi nhận.

Hãy thử lại khi gặp 5xx hoặc timeout. Không thử lại với 400, 401, hoặc 404: những mã này nghĩa là bản thân request đã sai, và gửi lại y nguyên sẽ thất bại theo cùng cách. Đặc biệt, 404 thường có nghĩa là phiên đã hết hạn.

Thứ tự

Hãy gửi callback ngay khi bạn có câu trả lời cuối cùng từ chủ thẻ. Nếu nó đến sau khi ACS đã hoàn tất xác thực thông qua /validate, nó vẫn được chấp nhận nhưng bị bỏ qua — kết quả final đầu tiên sẽ thắng.