Version Request

Endpoint

POST https://api.akua.la/v1/3ds/version

Request

{
  "merchant_id": "string (requerido)",
  "instrument_id": "string (opcional)",
  "card_number": "string (opcional)",
  "card_expiry_date": "string (opcional, formato MMYY)"
}

Campos del Request

Campo	Tipo	Requerido	Descripción
`merchant_id`	string	Sí	Identificador único del comercio en Akua
`instrument_id`	string	No	ID del instrumento de pago tokenizado (alternativa a `card_number`)
`card_number`	string	No*	Número de tarjeta (Primary Account Number)
`card_expiry_date`	string	No*	Fecha de expiración en formato MMYY (ej: `"1226"` para Dic 2026)

Importante: Debe proporcionar o bien instrument_id o bien card_number + card_expiry_date.

Response

{
  "timestamp": 1706543210000,
  "card_scheme": "VISA",
  "data": {
    "transaction_id": "akua-txn-12345",
    "threeds_server_trans_id": "8a880dc0-1234-5678-9abc-def012345678",
    "threeds_method_url": "https://acs.example.com/method",
    "version_recommendation": "2.2.0",
    "available_version": ["2.1.0", "2.2.0"],
    "acs_start_protocol_version": "2.1.0",
    "acs_end_protocol_version": "2.2.0",
    "ds_start_protocol_version": "2.1.0",
    "ds_end_protocol_version": "2.2.0",
    "acs_info_id": ["01", "02"],
    "instrument_id": "ins-abc123xyz"
  }
}

Campos del Response

Campo	Tipo	Descripción
`timestamp`	integer	Timestamp Unix en milisegundos
`card_scheme`	string	Esquema de la tarjeta (VISA, MASTERCARD)
`data.transaction_id`	string	ID de la transacción generado por Akua
`data.threeds_server_trans_id`	string	ID único para esta transacción 3DS (UUID)
`data.threeds_method_url`	string	URL para el Method Request (puede estar vacío)
`data.version_recommendation`	string	Versión 3DS recomendada para usar
`data.available_version`	array	Versiones 3DS disponibles
`data.acs_start_protocol_version`	string	Versión mínima soportada por ACS
`data.acs_end_protocol_version`	string	Versión máxima soportada por ACS
`data.ds_start_protocol_version`	string	Versión mínima soportada por Directory Server
`data.ds_end_protocol_version`	string	Versión máxima soportada por Directory Server
`data.acs_info_id`	array	IDs de información del ACS
`data.instrument_id`	string	ID del instrumento tokenizado (si aplica)

⚠️ Importante: El campo threeds_server_trans_id retornado en el Version Response debe:

Guardarse para usar en el Authenticate Request (campo opcional threeds_server_trans_id)
Usarse para el Method Request (parámetro threeDSServerTransID)
Usarse para el Result Request (campo requerido threeds_server_trans_id)

Este ID vincula todos los pasos del flujo 3DS para una misma transacción.

Cuándo Usar instrument_id vs card_number + card_expiry_date

instrument_id: Use este campo cuando ya tenga un token del instrumento de pago almacenado de una transacción previa. Esto es más seguro y cumple con PCI DSS.
card_number + card_expiry_date: Use estos campos cuando sea la primera vez que procesa esta tarjeta y no tenga un token todavía.