Initiate action

POST {your_base_url}/initiate_action

Called when the challenge window opens, and again each time the cardholder asks for a resend. This is where you actually deliver the credential — send the SMS, push the notification.

The request shape depends on the StepupType you returned from /step_up.

OTP

The ACS generates the code and validates it itself. Your platform only delivers what it is given.

{
  "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",
  "StepupType": "OTP",
  "StepupCounter": 1,
  "VerificationToken": "482913",
  "MessageVersion": "2.2.0",
  "RDXMessageVersion": "2.2.4",
  "MessageCategory": "01",
  "CardBrandName": "VISA",
  "Credentials": [{ "Id": "0b8ce7e2-8388-4b4c-9568-8f8da53c1b09", "Type": "OTPSMS" }]
}

Deliver VerificationToken unchanged

This is the code the ACS will compare the cardholder's input against. If your platform generates its own code instead, the cardholder receives one value while the ACS checks another, and every attempt fails until the retry limit is reached. Pass the value through verbatim.

Out-of-band

No credential value — instead you get the URL to call when the cardholder responds.

{
  "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",
  "StepupType": "OUTOFBAND",
  "StepupCounter": 1,
  "OOBCallbackUrl": "https://acs.example.cake.vn/oob-callback",
  "MessageVersion": "2.2.0",
  "RDXMessageVersion": "2.2.4",
  "MessageCategory": "01",
  "CardBrandName": "VISA",
  "Credentials": [{ "Id": "0b8ce7e2-8388-4b4c-9568-8f8da53c1b09", "Type": "OUTOFBANDOTHER" }]
}

OOBCallbackUrl is where you push the result — see OOB callback.

Response

A minimal acknowledgement is enough. Echo the identifying fields:

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

A delivery failure here does not abort the authentication. The ACS records it and still shows the challenge screen, so the cardholder can ask for a resend.

Resends

Each resend calls this endpoint again with the same StepupRequestId and StepupCounter incremented. Treat it as a redelivery within the existing session — do not open a new one, and do not invalidate the session you already have.

For OTP, the VerificationToken on a resend may differ from the previous call. Always deliver the value from the current request.