Setup 3DS authentication

POST/api/v1/bank/public/setup-authentication

Public endpoint

The A55Pay SDK calls this endpoint from the payer's browser. No Bearer token required. It initializes the 3DS Device Data Collection (DDC) process before card payment.

---

Request headers

Header	Value	Required
Content-Type	application/json	Yes

Request body

Field	Type	Required	Description
card_bin	string	Yes	First 6-8 digits of the card number
wallet_uuid	string (UUID)	Yes	Wallet associated with the charge
merchant_id	string (UUID)	Yes	Merchant identifier

---

Response fields

Field	Type	Description
session_id	string	DDC session identifier — pass to device_info.session_id
ddc_url	string	URL of the issuer's DDC iframe
ddc_jwt	string	JWT token for the DDC iframe
provider	string	3DS provider handling authentication
expires_at	string	ISO 8601 session expiration

---

HTTP status codes

Status	Description
200	3DS setup initialized
400	Invalid BIN or missing required fields
404	Wallet or merchant not found
422	Card BIN not eligible for 3DS
429	Rate limit exceeded
500	Internal server error

---

Code examples

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/public/setup-authentication \
  -H "Content-Type: application/json" \
  -d '{
    "card_bin": "402400",
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111"
  }'

Python

import requests

try:
    response = requests.post(
        "https://sandbox.api.a55.tech/api/v1/bank/public/setup-authentication",
        json={
            "card_bin": "402400",
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
        },
        headers={"Content-Type": "application/json"},
    )
    response.raise_for_status()
    setup = response.json()
    print(f"Session ID: {setup['session_id']}")
    print(f"DDC URL: {setup['ddc_url']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

try {
  const response = await fetch(
    "https://sandbox.api.a55.tech/api/v1/bank/public/setup-authentication",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        card_bin: "402400",
        wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        merchant_id: "11111111-1111-1111-1111-111111111111",
      }),
    }
  );

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const setup = await response.json();
  console.log(`Session ID: ${setup.session_id}`);
  console.log(`DDC URL: ${setup.ddc_url}`);
} catch (error) {
  console.error("3DS setup failed:", error.message);
}

---

Error response example

{
  "status": "error",
  "message": [
    {
      "code": "BIN_NOT_3DS_ELIGIBLE",
      "source": "authentication",
      "description": "Card BIN 999999 is not eligible for 3DS authentication"
    }
  ]
}

---

Pay charge →Submit payment with device_info after DDC.Validate 3DS →Handle 3DS challenge validation callback.Create charge →Create the charge with threeds_authentication: true.