Step-up

POST {your_base_url}/step_up

Được gọi khi ACS quyết định một giao dịch cần challenge. Hãy tạo một phiên xác thực cho chủ thẻ và trả về phương thức bạn muốn ACS hiển thị.

Đây là endpoint duy nhất nhận được PAN.

Request

{
  "ProcessorId": "cake-proc-01",
  "IssuerId": "cake-iss-01",
  "TransactionId": "9f6b6a2e-6f4e-4d0a-9b6e-2f9d6c1a7e10",
  "DSTransactionId": "660e8400-e29b-41d4-a716-446655440000",
  "StepupRequestId": "b2b6c9a4-1d0e-4e3a-8c8b-5a1f2d3c4b5a",
  "ThreeDSRequestorAuthenticationInd": "01",
  "MessageVersion": "2.2.0",
  "RDXMessageVersion": "2.2.4",
  "MessageCategory": "01",
  "RequestedStepupType": "OTP",
  "DeviceLocale": "vi-VN",
  "DeviceUserAgent": "Mozilla/5.0 ...",
  "MerchantInfo": {
    "MerchantName": "Shop ABC",
    "MerchantURL": "https://shop.example",
    "MerchantCategoryCode": "5411",
    "MerchantCountryCode": "704",
    "MerchantId": "m-123"
  },
  "PaymentInfo": {
    "CardNumber": "4012000000001091",
    "CardExpiryMonth": "07",
    "CardExpiryYear": "28",
    "CardHolderName": "NGUYEN VAN A"
  },
  "TransactionInfo": {
    "TransactionCurrency": "704",
    "TransactionAmount": 150000,
    "TransactionExponent": 0,
    "TransactionType": "GoodsOrService",
    "TransactionTimeStamp": "2026-07-19T13:05:01Z",
    "Channel": "WEB"
  },
  "StepupCounter": 1
}

Trường	Ghi chú
PaymentInfo.CardNumber	Số thẻ đầy đủ (PAN). Xem lưu ý về PCI trong phần giới thiệu
TransactionInfo.TransactionAmount	Đơn vị nhỏ nhất (minor units), theo tỉ lệ TransactionExponent — 150000 với exponent 0 là 150.000 VND
TransactionInfo.TransactionCurrency	Mã số ISO 4217 — 704 là VND
MerchantInfo	Được hiển thị cho chủ thẻ trong lúc challenge; hãy truyền nguyên vẹn sang app của bạn
StepupCounter	Luôn là 1 — step-up chỉ chạy một lần cho mỗi lần xác thực. Bộ đếm chỉ tăng lên qua các lần gửi lại /initiate_action
RequestedStepupType	Phương thức mà ACS muốn, khi nó có một ưu tiên nhất định — OTP hoặc OUTOFBAND. Không xuất hiện trong request khi ACS không có ưu tiên nào

Response

Hãy trả về phương thức bạn muốn hiển thị. Ví dụ dưới đây chọn phê duyệt out-of-band:

{
  "ProcessorId": "cake-proc-01",
  "IssuerId": "cake-iss-01",
  "TransactionId": "9f6b6a2e-6f4e-4d0a-9b6e-2f9d6c1a7e10",
  "StepupRequestId": "b2b6c9a4-1d0e-4e3a-8c8b-5a1f2d3c4b5a",
  "StepupType": "OUTOFBAND",
  "Status": "SUCCESS",
  "Credentials": [
    {
      "Id": "0b8ce7e2-8388-4b4c-9568-8f8da53c1b09",
      "Type": "OUTOFBANDOTHER"
    }
  ]
}

Trường	Bắt buộc	Mô tả
StepupType	Có	OUTOFBAND hoặc OTP
Status	Có	Xem bảng bên dưới
Credentials[].Id	Có	Định danh của bạn cho credential này; được echo lại ở các lần gọi sau
Credentials[].Type	Có	OUTOFBANDOTHER cho out-of-band, OTPSMS cho mã gửi qua SMS
Credentials[].Text	Không	Được chấp nhận, nhưng không được hiển thị — xem bên dưới

Nội dung hiển thị trên màn hình challenge

ACS host và render trang challenge, nên nội dung chủ thẻ đọc được cấu hình ở phía ACS, không phải được cung cấp theo từng giao dịch qua Credentials[].Text. Nếu bạn cần nội dung khác, hãy đề xuất trong quá trình onboarding thay vì gửi nó ở đây.

Cách response của bạn được diễn giải

Bạn trả về	transStatus	transStatusReason	Ý nghĩa
SUCCESS + StepupType: OUTOFBAND	C	—	Challenge, out-of-band — hiển thị trang chờ
SUCCESS + StepupType: OTP	C	—	Challenge, nhập mã — hiển thị form nhập
SUCCESS + một step-up type chưa được hỗ trợ	U	22	Sự cố kỹ thuật — xem bên dưới
FAILWITHFEEDBACK, REJECTED, BLOCKED, FAILURE	N	11	Bị từ chối, nghi ngờ gian lận
ERROR, bất kỳ status không xác định nào, timeout, hoặc không thể kết nối	U	22	Sự cố kỹ thuật

Các loại step-up được hỗ trợ hiện nay

ACS hiện chỉ render hai loại: OTP và OUTOFBAND. Xác thực bằng passkey đang nằm trong lộ trình phát triển.

Hợp đồng giao tiếp còn định nghĩa các loại khác — BIOMETRIC, KBA, OTPEMAIL, OTPIVR, CHOICE, OUTOFBANDTOKEN. Chúng chưa được hỗ trợ, không phải bị loại bỏ; hỗ trợ sẽ được bổ sung khi màn hình challenge cho chúng được xây dựng xong. Cho đến khi một loại khả dụng, trả về nó sẽ tạo ra transStatus là U với transStatusReason là 22, khiến giao dịch thất bại dù Status của bạn là SUCCESS.

Có hai lựa chọn tạm thời. Ánh xạ sang một loại được hỗ trợ — một mã gửi qua email hay IVR về bản chất vẫn là một mã chủ thẻ nhập vào, nên OTP có thể mang nó; và bất kỳ phê duyệt trong app nào đều là OUTOFBAND. Hoặc, nếu một loại bạn cần không thể ánh xạ được, hãy đề xuất trong quá trình onboarding để nó được lên lịch xây dựng.

WARNING

Timeout được xử lý giống như một lỗi, và cả hai đều không phê duyệt giao dịch. Nếu bạn không thể mở một phiên, ACS không thể gửi credential — nên xác thực sẽ thất bại thay vì được phê duyệt một cách âm thầm.

Chọn một phương thức

Hãy trả về phương thức mà chủ thẻ có thể thực sự hoàn tất ngay lúc này. Nếu họ đã cài app của bạn và bật push notification, OUTOFBAND là trải nghiệm tốt hơn. Nếu không, OTP tiếp cận được họ ở bất kỳ đâu.

Khi RequestedStepupType xuất hiện, hãy tuân theo nó nếu có thể. Điều đó có nghĩa là ACS đã quyết định phương thức nào phù hợp với chủ thẻ và giao dịch này, và đó cũng là phương thức mà màn hình challenge đã sẵn sàng để hiển thị.

Bạn có thể trả về một StepupType khác — nhưng khi đó ACS sẽ hủy xác thực thay vì hiển thị một sự không khớp, vì credential bạn sắp gửi không phải là loại chủ thẻ sắp được hỏi. Hiển thị một form nhập mã cho người vừa nhận được push notification còn tệ hơn là làm thất bại giao dịch.

Khi RequestedStepupType không xuất hiện, lựa chọn là của bạn: hãy trả về bất kỳ phương thức nào chủ thẻ có thể hoàn tất ngay lúc này.