3DS GateDocumentation
3DS Gate authenticates a payment and returns a result your order can act on. Integration is a server-side call and a redirect to the challenge; nothing else is required from the merchant.
Model in one paragraph. Your server creates an authentication session, receives a creq and a challenge URL, and redirects the buyer there. The buyer confirms with the issuer. The challenge posts back to your notificationUrl, your server verifies the signature and reads transStatus. Y proceeds to authorisation, N declines, U is unavailable, A is an attempted authentication outside the 3DS scope.
Before you start
| Base URL | https://api.3dsgate.com |
|---|---|
| Challenge host | https://acs.3dsgate.com/otp/ |
| Auth | Authorization: Bearer sk_live_… on server-side calls only |
| Content type | application/json |
| Message versions | 2.1.0, 2.2.0 |
| Idempotency | Idempotency-Key header, 24 h window |
What you send
A session needs the amount, currency, masked card context, buyer context and where to return. Card data may stay with your processor — the service works on the authentication decision, not on the PAN.
curl -X POST https://api.3dsgate.com/v2/authentications \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f14e45f-ceea-467a-9a3c-1f0b2e4d7a11" \
-d '{
"amount": 48690,
"currency": "BRL",
"messageVersion": "2.2.0",
"card": { "brand": "visa", "bin": "411111", "last4": "4417", "holderName": "M C SILVA" },
"buyer": { "email": "[email protected]", "phone": "+5511998124477", "locale": "pt-BR" },
"notificationUrl": "https://store.example/api/3ds/notify",
"returnUrl": "https://store.example/checkout/return"
}'What you get back
A 201 with the session identifiers and the challenge target. Redirect the buyer to challengeUrl — it is on the fixed host and already carries the encoded creq.
{
"authenticationId": "ath_01J9Z4K2V6",
"acsTransID": "4055bb18-efaa-4c6c-bbb7-1f44f0d0c8c0",
"dsTransID": "49dbeee6-4445-446c-b9c3-62351b0946d1",
"challengeUrl": "https://acs.3dsgate.com/otp/?creq=eyJ0aHJlZURTU2Vzc2lvblRyYW5zSUQiOi…",
"expiresAt": "2026-10-28T15:12:00Z"
}What you must do
- Verify the signature on every notification before acting on it. The header
X-3DS-Signaturecarries an HMAC-SHA256 of the raw body with your endpoint secret. - Trust
transStatus, nothing else. Not the redirect, not a query parameter. A buyer can reachreturnUrlwithout finishing. - Handle
U. Unavailable is not a decline; route it per your risk policy instead of failing the order outright. - Keep the reference (
authenticationId) on the order. It is the key to the audit trail if the charge is contested.
Next
Quickstart
Wire the first authenticated order against the sandbox.
Challenge lifecycle
States, timeouts, retries and what happens on abandonment.
Documentation version 2026-10. Historical versions are available on request.