Endpoint bạn triển khai

Cake ACS gọi ba endpoint trên nền tảng của bạn trong quá trình xác thực. Trang này mô tả những điểm chung; trang riêng của từng endpoint mô tả các trường cụ thể của nó.

POST {your_base_url}/step_up
POST {your_base_url}/initiate_action
POST {your_base_url}/validate

Cả ba đều dùng Content-Type: application/json và kỳ vọng một response JSON với HTTP 200.

Các trường chung

Mọi request đều mang theo các trường này. Hãy echo lại cả bốn giá trị trong response — ACS dùng chúng để khớp phản hồi của bạn với phiên xác thực đang diễn ra.

Trường	Kiểu	Mô tả
ProcessorId	string	Định danh ACS đang gọi. Được thống nhất trong quá trình onboarding
IssuerId	string	Định danh bạn. Được thống nhất trong quá trình onboarding
TransactionId	string	Duy nhất cho mỗi lần xác thực, không đổi xuyên suốt cả ba endpoint
StepupRequestId	string	Duy nhất cho mỗi phiên challenge, không đổi qua các lần gửi lại

Hai trường phiên bản cũng được gửi trên mọi request:

Trường	Ví dụ	Mô tả
MessageVersion	2.2.0	Phiên bản EMV 3-D Secure mà merchant đang sử dụng
RDXMessageVersion	2.2.4	Phiên bản của hợp đồng giao tiếp này

Giá trị Status

Trường Status trong response của bạn là thứ ACS dựa vào để hành động. Ý nghĩa cụ thể khác nhau tùy endpoint — xem trang tương ứng — nhưng hình thức thì giống nhau:

Status	Ý nghĩa
SUCCESS	Thao tác đã hoàn tất
RETRY	Chưa xong; hỏi lại sau. Chỉ có ý nghĩa với /validate
REJECTED	Chủ thẻ bị từ chối
FAILWITHFEEDBACK	Bị từ chối, kèm lý do để hiển thị
BLOCKED	Bị từ chối; thẻ hoặc tài khoản đang bị khóa
FAILURE	Bị từ chối vì lý do khác
ERROR	Nền tảng của bạn không thể xử lý request

Timeout

ACS áp dụng một timeout cho mỗi lệnh gọi. Nếu endpoint của bạn không trả lời kịp, ACS sẽ xử lý y hệt như một response ERROR.

WARNING

Không có cơ chế thử lại (retry). Xác thực được quyết định dựa trên câu trả lời đầu tiên — hoặc lần timeout đầu tiên. Hãy trả về ERROR nhanh thay vì giữ kết nối mở; một kết nối bị giữ sẽ tiêu tốn thời gian còn lại của chủ thẻ trong cửa sổ challenge.

Xác thực (Authentication)

Các request từ ACS đến nền tảng của bạn không được ký ở tầng ứng dụng. Chúng được bảo vệ ở tầng mạng bởi các dải IP nguồn đã trao đổi trong quá trình onboarding. Chiều ngược lại — OOB callback của bạn — có được ký; xem Bảo mật.

Dữ liệu chủ thẻ

Request /step_up chứa toàn bộ PAN, vì nền tảng của bạn cần nó để nhận diện chủ thẻ. Đây là endpoint duy nhất mang theo nó. Hãy coi request này nằm trong phạm vi PCI DSS: không log body, và không lưu trữ PAN bên ngoài môi trường dữ liệu chủ thẻ hiện có của bạn.