Ecommerce - Alignet Integration Docs

El servicio de autorización Ecommerce permite procesar pagos de comercio electrónico mediante el endpoint POST /authorize.

Esta trama debe utilizarse cuando la transacción proviene de un canal no presencial, como checkout web, mobile checkout, link de pago o integración server-to-server.

Endpoint

POST /authorize

Request

{
  "frame_type": "ecommerce",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "internal_operation_number": "ORDER-0000000079",
  "amount": "38980",
  "currency": "604",
  "card": {
    "pan": "Cifrado",
    "expiry_date": "cifrado",
    "security_code": "cifrado"
  },
  "card_holder": {
    "first_name": "Fabricio",
    "last_name": "Iman",
    "email_address": "fabricio.iman@pay-me.com",
    "line_1": "Rupertuups"
  },
  "installments": {
    "number_of_installments": "04",
    "id_plan": "145",
    "grace_period": "02"
  },
  "authentication": {
    "3d_secure": {
      "payment_implementation_mode_indicator": "08",
      "cavv": "kANvskBe2eEnngBkKwx45YQBV7E=",
      "version": "2.1.0"
    }
  },
  "metadata": {
    "sucursal": "Sucursal 1"
  }
}

Descripción de campos

Campo	Tipo	Obligatorio	Longitud	Descripción
`frame_type`	string	Sí	enum	Canal de la transacción. Para Ecommerce debe enviarse `ecommerce`.
`merchant_identifier`	string UUID	Sí	36	Identificador único del comercio. Se entrega al registrar el comercio durante el onboarding.
`brand`	string	Sí	enum	Marca de la tarjeta. Valores permitidos: `visa`, `mscd`.
`internal_operation_number`	string	Sí	1-40	Referencia o número de orden del comercio. Debe ser único por comercio.
`amount`	string	Sí	6-17	Monto de la operación sin decimales. Ejemplo: `389.80 PEN = "38980"`.
`currency`	string	Sí	3	Código ISO 4217 numérico. Ejemplo: `604` = PEN, `840` = USD.
`card.pan`	string	Sí	13-19	Número de tarjeta cifrado.
`card.expiry_date`	string	Sí	4	Fecha de expiración cifrada.
`card.security_code`	string	No	3-4	Código de seguridad cifrado.
`card_holder.first_name`	string	No	1-26	Nombre del tarjetahabiente. Puede ser utilizado para validaciones AVS.
`card_holder.last_name`	string	No	1-26	Apellido del tarjetahabiente. Puede ser utilizado para validaciones AVS.
`card_holder.email_address`	string	No	email	Correo electrónico del tarjetahabiente.
`card_holder.line_1`	string	No	1-40	Dirección del tarjetahabiente. Puede ser utilizada para validaciones AVS.
`installments.number_of_installments`	string	No	1-4	Número de cuotas. Debe enviarse solo con dígitos. Ejemplo: `04`.
`installments.id_plan`	string	No	1+	Identificador del plan de cuotas configurado por el adquirente.
`installments.grace_period`	string	No	2	Periodo de gracia expresado en meses. Ejemplo: `02`.
`authentication.3d_secure.payment_implementation_mode_indicator`	string	No	enum	Indicador de implementación 3DS.
`authentication.3d_secure.cavv`	string	No	1-40	Valor CAVV obtenido como resultado de la autenticación 3DS.
`authentication.3d_secure.version`	string	No	5-8	Versión del protocolo 3DS. Ejemplo: `2.1.0`.
`metadata`	object	No	—	Campos libres enviados por el comercio en formato key-value. Se almacenan con la transacción.

Valores permitidos

`frame_type`

Valor	Descripción
`ecommerce`	Transacción de comercio electrónico.

`brand`

Valor	Descripción
`visa`	Transacción con tarjeta Visa.
`mscd`	Transacción con tarjeta Mastercard.

`authentication.3d_secure.payment_implementation_mode_indicator`

Valor	Descripción
`05`	Transacción 3DS con CAVV.
`06`	Attempt Mastercard.
`07`	Attempt Visa.
`08`	Transacción con datos 3DS.

Consideraciones sobre montos

El campo amount debe enviarse sin punto decimal. El monto se calcula aplicando el exponente de la moneda:

Monto enviado = monto real × 10^exponente de la moneda

Ejemplo para moneda PEN:

Monto real	Currency	Valor enviado
10.00	`604`	`1000`
389.80	`604`	`38980`
1,250.50	`604`	`125050`

Consideraciones sobre moneda

El campo currency debe enviarse en formato ISO 4217 numérico.

Moneda	Código ISO 4217 numérico
PEN	`604`
USD	`840`

Consideraciones sobre tarjeta

Los datos sensibles de tarjeta deben enviarse cifrados.

Campo	Cifrado requerido
`card.pan`	Sí
`card.expiry_date`	Sí
`card.security_code`	Sí

Consideraciones sobre cuotas

El objeto installments debe enviarse únicamente cuando la operación aplique a un pago en cuotas.

{
  "installments": {
    "number_of_installments": "04",
    "id_plan": "145",
    "grace_period": "02"
  }
}

Reglas

Regla	Descripción
Número de cuotas	`number_of_installments` debe contener solo dígitos.
Plan de cuotas	`id_plan` debe corresponder a un plan habilitado para el comercio.
Periodo de gracia	`grace_period` debe enviarse en formato de dos dígitos.
Operación sin cuotas	Si la operación no aplica a cuotas, el objeto `installments` puede omitirse.

Consideraciones sobre 3DS

El objeto authentication.3d_secure debe enviarse cuando la transacción cuente con información de autenticación 3DS.

{
  "authentication": {
    "3d_secure": {
      "payment_implementation_mode_indicator": "08",
      "cavv": "kANvskBe2eEnngBkKwx45YQBV7E=",
      "version": "2.1.0"
    }
  }
}

Metadata

El campo metadata permite enviar información adicional del comercio para fines de trazabilidad, reportería o conciliación.

{
  "metadata": {
    "sucursal": "Sucursal 1",
    "canal": "web",
    "numero_pedido": "PED-123456"
  }
}

Validaciones principales

Antes de enviar una autorización Ecommerce, validar lo siguiente:

Validación	Regla
Comercio	`merchant_identifier` debe estar activo y habilitado para operar.
Canal	`frame_type` debe ser `ecommerce`.
Marca	`brand` debe ser `visa` o `mscd`.
Orden	`internal_operation_number` debe ser único por comercio.
Monto	`amount` debe enviarse sin decimales.
Moneda	`currency` debe enviarse en formato ISO 4217 numérico.
Tarjeta	Los campos sensibles deben enviarse cifrados.
Cuotas	Si se envía `installments`, el plan debe estar habilitado para el comercio.
3DS	Si se envía información 3DS, debe incluir datos válidos de autenticación.
Metadata	Los campos enviados en `metadata` deben respetar formato key-value.

Ejemplo mínimo

{
  "frame_type": "ecommerce",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "internal_operation_number": "ORDER-0000000080",
  "amount": "1000",
  "currency": "604",
  "card": {
    "pan": "Cifrado",
    "expiry_date": "cifrado",
    "security_code": "cifrado"
  }
}

Ejemplo con cuotas

{
  "frame_type": "ecommerce",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "internal_operation_number": "ORDER-0000000081",
  "amount": "38980",
  "currency": "604",
  "card": {
    "pan": "Cifrado",
    "expiry_date": "cifrado",
    "security_code": "cifrado"
  },
  "installments": {
    "number_of_installments": "04",
    "id_plan": "145",
    "grace_period": "02"
  }
}

Ejemplo con 3DS

{
  "frame_type": "ecommerce",
  "merchant_identifier": "b656d278-f047-4e23-9fa5-96c5818b5c8d",
  "brand": "visa",
  "internal_operation_number": "ORDER-0000000082",
  "amount": "38980",
  "currency": "604",
  "card": {
    "pan": "Cifrado",
    "expiry_date": "cifrado",
    "security_code": "cifrado"
  },
  "authentication": {
    "3d_secure": {
      "payment_implementation_mode_indicator": "08",
      "cavv": "kANvskBe2eEnngBkKwx45YQBV7E=",
      "version": "2.1.0"
    }
  }
}

Response

La respuesta de una autorización Ecommerce se encuentra documentada en la página de respuesta general para autorizaciones.

Response de autorización

Ver estructura de respuesta para Ecommerce y POS.

​Endpoint

​Request

​Descripción de campos

​Valores permitidos

​frame_type

​brand

​authentication.3d_secure.payment_implementation_mode_indicator

​Consideraciones sobre montos

​Consideraciones sobre moneda

​Consideraciones sobre tarjeta

​Consideraciones sobre cuotas

​Reglas

​Consideraciones sobre 3DS

​Metadata

​Validaciones principales

​Ejemplo mínimo

​Ejemplo con cuotas

​Ejemplo con 3DS

​Response