Getting started

Integrating with the Cake ACS is a short exchange of connection details followed by two end-to-end test flows. This page covers what you need to agree on before writing code.

What you provide to Cake

Item	Why
Base URL of your authentication service	Where the ACS sends /step_up, /initiate_action, and /validate
Card ranges to authenticate	The ACS only answers for cards it is configured to serve
Supported challenge methods	Whether your platform can deliver an OTP, an out-of-band approval, or both
Source IP ranges	So your inbound traffic is allowed through

What Cake provides to you

Item	Why
ProcessorId and IssuerId	Sent on every request; echo them back unchanged
OOB callback URL	Where to push an out-of-band result. Also sent on each /initiate_action as OOBCallbackUrl
Shared HMAC key	A hex string used to sign your callback bodies — see Security

WARNING

The shared HMAC key is a credential. Exchange it over a secure channel, store it the way you store other production secrets, and rotate it on the same schedule. Never commit it or send it by email.

Implement three endpoints

Your service must accept POST with Content-Type: application/json on three paths, relative to the base URL you provided:

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

Each request carries ProcessorId, IssuerId, TransactionId, and StepupRequestId. Echo all four back in your response — the ACS uses them to match the response to the in-flight authentication.

See Endpoints you implement for the full contract.

Decide how the cardholder is challenged

Your /step_up response drives everything that follows. Return StepupType: "OTP" and the ACS renders a code entry form; return StepupType: "OUTOFBAND" and it renders a waiting page while your app collects the approval.

For OTP the ACS generates the code and validates it itself — your platform only delivers it. This matters: deliver exactly the VerificationToken value you receive, unchanged, or the cardholder will enter a code the ACS cannot match.

Go-live checklist

• [ ] Base URL, card ranges, and source IP ranges exchanged
• [ ] ProcessorId, IssuerId, and the shared HMAC key received and stored
• [ ] All three endpoints reachable from the ACS and returning valid responses
• [ ] Callback signed correctly — a signed test request returns 200
• [ ] One OTP flow completed end to end in the test environment
• [ ] One out-of-band flow completed end to end in the test environment