Step-up

POST {your_base_url}/step_up

Called when the ACS decides a transaction needs a challenge. Create an authentication session for the cardholder and return the method you want the ACS to render.

This is the only endpoint that receives the 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
}

Field	Notes
PaymentInfo.CardNumber	Full PAN. See the PCI note in the introduction
TransactionInfo.TransactionAmount	Minor units, scaled by TransactionExponent — 150000 with exponent 0 is 150,000 VND
TransactionInfo.TransactionCurrency	ISO 4217 numeric — 704 is VND
MerchantInfo	Shown to the cardholder during the challenge; pass it through to your app
StepupCounter	Always 1 — step-up runs once per authentication. The counter only advances across /initiate_action resends
RequestedStepupType	The method the ACS wants, when it has a preference — OTP or OUTOFBAND. Omitted when it has none

Response

Return the method you want rendered. This example selects an out-of-band approval:

{
  "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"
    }
  ]
}

Field	Required	Description
StepupType	Yes	OUTOFBAND or OTP
Status	Yes	See the table below
Credentials[].Id	Yes	Your identifier for this credential; echoed back on later calls
Credentials[].Type	Yes	OUTOFBANDOTHER for out-of-band, OTPSMS for an SMS code
Credentials[].Text	No	Accepted, but not rendered — see below

Wording on the challenge screen

The ACS hosts and renders the challenge page, so the text the cardholder reads is configured on the ACS side, not supplied per transaction through Credentials[].Text. If you need different wording, raise it during onboarding rather than sending it here.

How your response is interpreted

You return	transStatus	transStatusReason	Meaning
SUCCESS + StepupType: OUTOFBAND	C	—	Challenge, out-of-band — a waiting page is rendered
SUCCESS + StepupType: OTP	C	—	Challenge, code entry — an input form is rendered
SUCCESS + a step-up type not yet supported	U	22	Technical issue — see below
FAILWITHFEEDBACK, REJECTED, BLOCKED, FAILURE	N	11	Declined, suspected fraud
ERROR, any unrecognised status, a timeout, or unreachable	U	22	Technical issue

Step-up types supported today

The ACS currently renders two: OTP and OUTOFBAND. Passkey authentication is on the roadmap.

The contract defines other types — BIOMETRIC, KBA, OTPEMAIL, OTPIVR, CHOICE, OUTOFBANDTOKEN. They are not supported yet, not ruled out; support is added as the challenge screens for them are built. Until a type is available, returning it produces transStatus U with transStatusReason 22, so the transaction fails even though your Status was SUCCESS.

Two options in the meantime. Map to a supported type — an email or IVR code is still a code the cardholder types, so OTP carries it, and any in-app approval is OUTOFBAND. Or, if a type you need cannot be mapped, raise it during onboarding so it can be scheduled.

WARNING

A timeout is treated the same as an error, and neither approves the transaction. If you cannot open a session, the ACS cannot deliver a credential — so the authentication fails rather than silently passing.

Choosing a method

Return the method the cardholder can actually complete right now. If they have your app installed and push notifications enabled, OUTOFBAND is the better experience. If not, OTP reaches them anywhere.

When RequestedStepupType is present, honour it if you can. It means the ACS has already decided which method suits this cardholder and this transaction, and it is the method the challenge screen is prepared to render.

You may return a different StepupType — but the ACS will then abort the authentication rather than render a mismatch, because the credential you are about to deliver is not the one the cardholder is about to be asked for. Showing a code entry form to someone who just received a push notification is worse than failing the transaction.

When RequestedStepupType is absent, the choice is yours: return whichever method the cardholder can complete right now.