Suscripciones

Introducción

Las suscripciones de Lukapay le permiten aceptar fácilmente pagos con tarjeta de crédito y débito de manera recurrente. Cuando usa esta biblioteca, Lukapay afilia los datos de un cliente por medio de una librería en JavaScript sin que necesite tener cumplimiento de PCI, ya que los datos de pago del comprador se tokenizan y se envían directamente a los servidores de los procesadores de pago.

Una vez se realiza la afiliación de la tarjeta de crédito del cliente, la empresa podrá realizar pagos por medio de un API sin necesidad de aprobación previa del cliente. Este se podrá listar las tarjetas de un suscriptor y eliminarlas en caso que no se desee seguir realizando pagos con esa tarjeta.

Requerimientos

Para poder realizar la afiliación del suscriptor y sus métodos de pago es necesario integrar la librería JavaScript de Lukapay.

Luego por medio de nuestra API Rest podrá realizar los pagos recurrentes, listar y eliminar las tarjetas de crédito de un cliente.

Métodos disponibles

El proceso de suscripciones se divide en dos partes:

Crear token del suscriptor: Afiliación de tarjetas de crédito/débito y almacenamiento en bóveda vía Lukapay JS.

Checkout:: Crear una transacción para un comprador existente vía API Rest:

• Autenticación
• Obtener lista de tarjetas del cliente
• Pagar con una tarjeta de crédito de la bóveda
• Eliminar una tarjeta de crédito de la bóveda.

Crear token del suscriptor

A continuación se proporcionan las especificaciones para implementar la librería JavaScript de Lukapay que se utilizará para la afiliación de los clientes y la tokenización de sus medios de pago.

Métodos de pago

Nombre	Moneda	Clave	Ambiente
Tarjeta de crédito/débito	USD	tdc_bs	Producción
Tarjeta de crédito/débito	CLP	tbk_oneclick	Calidad

Implementación de Luka JS

Ver documentación de librería Luka JS.

Registrar tarjeta

Dependiendo de la moneda seleccionada, el usuario debe completar el formulario de registro introduciendo los datos de la tarjeta de crédito/débito.

Formulario de registro para dólares americanos.

Checkout

Este método se usa para generar un cargo mensual al comprador registrado desde la aplicación del comercio quien controla el flujo de pago de un extremo a otro. Pasos necesarios para este flujo:

• Generar un token para la autenticación de la aplicación.
• Recopile y envíe información de pago del comprador vía API Rest.
• Obtenga el objeto con la respuesta LukaPaymentResult.
• Complete la transacción en la aplicación del comercio.

La URL está especificada en Ambientes.

La autenticación se realiza a través de un token (JWT) que retorna el método de login con las credenciales proporcionadas por Lukapay. Ver documentación.

Obtener la lista de tarjetas del cliente.

Este método permitirá obtener el listado de las tarjetas que el cliente tiene registradas en la bóveda. Este paso es necesario para poder indicar cuál tarjeta de crédito se usará para realizar el pago con dólares americanos (USD).

Para obtener las tarjetas del cliente deberá proporcionar el valor del campo LukapayId que se devuelve en al momento de crear el token de la tarjeta y que el comercio debe asociar al usuario en su propia base de datos.

Las especificaciones del método son las siguientes:

Request

GET {URL}/api/v1/tarjetacredito/servicio/{LukapayId}

Headers

Content-Type: application/json
Authorization: Bearer {token}

Response

Body

Se devuelve una lista de objetos con la siguiente información de la tarjetas de crédito/débito

Nombre	Descripción	Tipo
Id	Número identificador de la tarjeta en la base de datos de Lukapay	Number
UltimosCuatroDigitos	Últimos cuatro dígitos de la tarjeta	String
SubTipoTarjeta	Indica si la tarjeta es de crédito o débito	String
TipoTarjeta	Indica el tipo de la tarjeta de crédito. Ejemplo: VISA, MASTER	String
CategoriaTarjeta	Indica si la tarjeta es de tipo comercial o personal	String
Bin	El número de identificación bancaria (BIN). Estos son los primeros 4 a 6 dígitos del número de la tarjeta de crédito	String
FechaVencimiento	Fecha de expiración de la tarjeta con formato MM/YYYY	String
Pais	Código ISO del país de emisión de la tarjeta de crédito	String
EstaBoveda	Indica si la tarjeta está asociada a la bóveda del usuario	Boolean
Direccion	Objeto con la dirección de facturación de la tarjeta	Object
Descripcion	Nombre o descripción proporcionado por el usuario para identificar fácilmente la tarjeta	String

Ejemplos de uso

Request

GET {URL}/api/v1/tarjetacredito/servicio/560356a272d9

Response body

[
    {
        "Id": 1,
        "UltimosCuatroDigitos": "1111",
        "SubTipoTarjeta": "CREDIT",
        "TipoTarjeta": "VISA",
        "CategoriaTarjeta": "CONSUMER",
        "Bin": "111111",
        "FechaVencimiento": "03/2023",
        "Pais": "US",
        "EstaBoveda": true,
        "Direccion": {
            "Id": 0,
            "Direccion": "Calle 1",
            "Ciudad": "Guatire",
            "Estado": "Miranda",
            "CodigoPostal": "1111"
        },
        "Descripcion": ""
    }
]

Pagar con una tarjeta de crédito de la bóveda

A través de esta función podrá generar una solicitud de pago con la información de la tarjeta registrada previamente por el usuario.

Pagar con USD

Este método requiere la información de la tarjeta de crédito/débito obtenida en el flujo "Obtener lista de tarjetas del cliente" para el objeto.

Las especificaciones del método son las siguientes:

Request

POST {URL}/api/v1/transaccion

Headers

Content-Type: application/json
Authorization: Bearer {token}

Body

Nombre	Descripción	Tipo	Obligatorio
EmailTarjetaHabiente	Correo electrónico del usuario	String	Sí
IdCanal	Identificador del canal por donde se está consumiendo el servicio. Valor por defecto: 2	Número	No
IdTraza	Identificador de la transacción en el sistema del comercio. Este campo se utilizará luego para consultar el estatus de una transacción.	String	Sí
Moneda	Código ISO de la moneda. Ejemplo: USD, CLP	String	No
Monto	Monto de la transacción o pago	Número	Sí
Referencia	Identificador del pago de cara al cliente. Ejemplo: número de factura, identificación del contrato, etc.	String	No
TarjetaCredito	Información de la tarjeta que se usará para realizar el pago. Se obtiene del método de consulta de tarjetas de crédito.	Objeto	Sí
TarjetaHabiente	Información del usuario pagador	Objeto	Sí

Propiedades del objetos

TarjetaCredito

Nombre	Descripción	Tipo
Id	Número identificador de la tarjeta en la base de datos de Lukapay (Obligatorio)	Número
UltimosCuatroDigitos	Últimos cuatro dígitos de la tarjeta	String
SubTipoTarjeta	Indica si la tarjeta es de crédito o débito	String
TipoTarjeta	Indica el tipo de la tarjeta de crédito. Ejemplo: VISA, MASTER	String
CategoriaTarjeta	Indica si la tarjeta es de tipo comercial o personal	String
Bin	El número de identificación bancaria (BIN). Estos son los primeros 4 a 6 dígitos del número de la tarjeta de crédito.	String
FechaVencimiento	Fecha de expiración de la tarjeta con formato MM/YYYY	String
Pais	Código ISO del país de emisión de la tarjeta de crédito	String

TarjetaHabiente

Nombre	Descripción	Tipo	Obligatorio
Apellido	Apellido del usuario que realiza la operación	String	No
Nombre	Nombre del usuario que realiza la operación	String	No
NúmeroIdentificacionPersonal	Cédula o número de identidad del usuario	String	No
NumeroTelefono	Número de teléfono del usuario	String	No
LukapayId	Identificación de registro del usuario en la bóveda de tarjetas (UUID)	String	Sí

Response

Nombre	Descripción	Tipo
Canal	Indica el canal que se está utilizando para aplicar el pago en Lukapay	Number
CargosAdicionales	Objeto que contiene cargos adicionales.	Object
Cuotas	Objeto que contiene información sobre cuotas.	Object
Descripción	Contiene la respuesta de la aplicación del pago, como estatus de la transacción y cualquier información adicional	String
Exitoso	Indica si la transacción fue exitosa o no. Se utiliza para validar la respuesta	Boolean
FechaOperacion	Fecha que ocurrió la transacción	String
InfoProceso	Objeto que contiene información más detallada del estatus de la transacción	Object
InfoTarjeta	Objeto que contiene información de la tarjeta de crédito utilizada para realizar el pago. Solo aplica para pagos con tarjeta	Object
InfoUsuarioPagador	Objeto que devuelve información básica del usuario que realiza el pago	Object
MedioDePago	Indica el método de pago que se utilizó	String
MerchantId	Referencia de la transacción del merchant utilizado para aplicar el pago	String
Moneda	Código de la moneda utilizada para realizar el pago	String
Monto	Indica el monto del pago realizado	Number
MontoOriginal	Objeto con información del monto original. Se utiliza cuando se debe aplicar una conversión de moneda	Object
MontoUsd	Valor del monto en dólar estadounidense. Se utiliza cuando se especifica el MontoOriginal	Number
TarjetaHabiente	Objeto que contiene información del pagador (en caso de haber sido especificado)	Object
TransaccionId	Referencia de la transacción en Lukapay	Number
TransaccionMerchantId	Referencia de la transacción del merchant utilizado para aplicar el pago	Number
TrazaId	Identificador interno del comercio. En caso de que el comercio no lo proporcione se genera un código aleatorio.	String

Los atributos de los objetos están especificados en Respuesta de transacción.

Ejemplos de uso

{
   "Monto":100,
   "TarjetaHabiente": {
      "Nombre":"Jhon",
      "Apellido":"Doe",
      "LukapayId":"560356a272d9"
   },
   "TarjetaCredito": {
        "Id": 1,
        "UltimosCuatroDigitos": "1111",
        "SubTipoTarjeta": "CREDIT",
        "TipoTarjeta": "VISA",
        "CategoriaTarjeta": "CONSUMER",
        "Bin": "111111",
        "FechaVencimiento": "03/2023",
        "Pais": "US",
   },
   "IdTraza":"1234567890",
   "Moneda":"USD",
   "EmailTarjetaHabiente":"usuario@mail.com",
   "IdCanal":2,
   "Referencia":"000265700237"
}

{
  "Monto": 100.0,
  "MontoUsd": 100.0,
  "InfoProceso": {
    "EstatusProcesamiento": "success",
    "CodigoRespuestaCvv": "N/D"
  },
  "TarjetaHabiente": {
    "Nombre":"Jhon",
    "Apellido":"Doe",
    “LukapayId”:”560356a272d9”
    "NumeroIdentificacionPersonal": null,
    "NumeroTelefono": null,
    "LukapayId": "560356a272d9"
  },
  "InfoUsuarioPagador": {
    "Nombre": "Jhon",
    "Apellido": "Doe",
    "NumeroIdentidad": null,
    "NumeroTelefono": null,
    "Email": "usuario@mail.com"
  },
  "Moneda": "USD",
  "InfoTarjeta": {
    "Id": 1,
    "UltimosCuatroDigitos": "1111",
    "SubTipoTarjeta": "CREDIT",
    "TipoTarjeta": "VISA",
    "CategoriaTarjeta": "CONSUMER",
    "Bin": "111111",
    "FechaVencimiento": "03/2023",
    "Pais": "US",
  },
  "TransaccionId": 102143,
  "TransaccionMerchantId": 1108334200,
  "Descripcion": "success",
  "TrazaId": "1234567890",
  "Exitoso": true,
  "Canal": "Api",
  "MedioDePago": "Débito",
  "MontoOriginal": null,
  "MerchantId": null,
  "FechaOperacion": null,
  "CargosAdicionales": null,
  "Cuotas": null
}

Pagar con CLP

Para pagar con una tarjeta registrada para pesos chilenos no hace falta seleccionar una tarjeta, solamente se necesita enviar el LukapayId.

Las especificaciones del método son las siguientes:

Request

POST {URL}/api/v1/transaccion/transbank.authorize

Headers

Content-Type: application/json
Authorization: Bearer {token}

Body

Nombre	Descripción	Tipo	Obligatorio
Email	Correo electrónico del usuario	String	Sí
TrazaId	Identificador de la transacción en el sistema del comercio. Este campo se utilizará luego para consultar el estatus de una transacción.	String	Sí
Moneda	Código ISO de la moneda. Ejemplo: CLP	String	Sí
Monto	Monto de la transacción o pago	Number	Sí
Referencia	Identificador del pago de cara al cliente. Ejemplo: número de factura, identificación del contrato, etc.	String	No
LukapayId	Identificación de registro del usuario en la bóveda de tarjetas.	String	Sí

Response

Nombre	Descripción	Tipo
Canal	Indica el canal que se está utilizando para aplicar el pago en Lukapay	Number
CargosAdicionales	Objeto que contiene cargos adicionales.	Object
Cuotas	Objeto que contiene información sobre cuotas.	Object
Descripción	Contiene la respuesta de la aplicación del pago, como estatus de la transacción y cualquier información adicional	String
Exitoso	Indica si la transacción fue exitosa o no. Se utiliza para validar la respuesta	Boolean
FechaOperacion	Fecha que ocurrió la transacción	String
InfoProceso	Objeto que contiene información más detallada del estatus de la transacción	Object
InfoTarjeta	Objeto que contiene información de la tarjeta de crédito utilizada para realizar el pago. Solo aplica para pagos con tarjeta	Object
InfoUsuarioPagador	Objeto que devuelve información básica del usuario que realiza el pago	Object
MedioDePago	Indica el método de pago que se utilizó	String
MerchantId	Referencia de la transacción del merchant utilizado para aplicar el pago	String
Moneda	Código de la moneda utilizada para realizar el pago	String
Monto	Indica el monto del pago realizado	Number
MontoOriginal	Objeto con información del monto original. Se utiliza cuando se debe aplicar una conversión de moneda	Object
MontoUsd	Valor del monto en dólar estadounidense. Se utiliza cuando se especifica el MontoOriginal	Number
TarjetaHabiente	Objeto que contiene información del pagador (en caso de haber sido especificado)	Object
TransaccionId	Referencia de la transacción en Lukapay	Number
TransaccionMerchantId	Referencia de la transacción del merchant utilizado para aplicar el pago	Number
TrazaId	Identificador interno del comercio. En caso de que el comercio no lo proporcione se genera un código aleatorio.	String

Los atributos de los objetos están especificados en Respuesta de transacción.

Ejemplos de uso

Request body

{
    "Moneda": "CLP",
    "Monto": 100,
    "TrazaId": "1234567890",
    "LukapayId": "560356a272d9",
    "Email": "example@mail.com",
    "Referencia": ""
}

Response body

{
    "Monto": 100.0,
    "MontoUsd": 0.0,
    "InfoProceso": {
        "EstatusProcesamiento": "success",
        "CodigoRespuestaCvv": null
    },
    "TarjetaHabiente": {
        "Nombre": "John",
        "Apellido": "Doe",
        "NumeroIdentificacionPersonal": "",
        "NumeroTelefono": null,
        "LukapayId": "6353a328-ef92-454d-826b-f59a01ca62d3"
    },
    "InfoUsuarioPagador": {
        "Nombre": "John",
        "Apellido": "Doe",
        "NumeroIdentidad": null,
        "NumeroTelefono": null,
        "Email": "example@mail.com"
    },
    "Moneda": "CLP",
    "InfoTarjeta": null,
    "TransaccionId": 102144,
    "TransaccionMerchantId": 1108334200,
    "Descripcion": "transacción exitosa",
    "TrazaId": "1234567890",
    "Exitoso": true,
    "Canal": "Api",
    "MedioDePago": "Transbank",
    "MontoOriginal": null,
    "MerchantId": null,
    "FechaOperacion": null,
    "CargosAdicionales": null,
    "Cuotas": null
}

Verificar el estado de una transacción

Ver Consulta de transacciones.

Eliminar una tarjeta de crédito de la bóveda

Este método permitirá eliminar una tarjeta de crédito de la bóveda. Se debe enviar el ID de la tarjeta a eliminar y el LukapayId del usuario.

Las especificaciones del método son las siguientes:

Request

• USD:

DELETE {URL}/api/v1/tarjetacredito/{idTarjeta}/user/{LukapayId}

• CLP

DELETE {URL}/api/v1/transaccion/transbank.unsubscribe/{LukapayId}

Headers

Content-Type: application/json
Authorization: Bearer {token}

Response

El método devuelve el código estado de respuesta 202 (Accepted) en caso de que la operación sea exitosa, de lo contrario se devuelve un código de error.

Códigos de errores

Código	Mensaje
400	la moneda no está soportada
400	el correo electrónico es obligatorio
400	la tarjeta ya se encuentra registrada
400	no se consiguió la tarjeta de crédito
400	ocurrió un error verificando la información de la tarjeta de crédito
400	identificador de tarjeta inválido
400	identificador de usuario inválido
401	acceso no autorizado
401	usuario no registrado
401	no se consiguieron parámetros de consulta válidos
402	monto incorrecto
404	no se encontró la tarjeta de crédito
409	ocurrió un error procesando la transacción
500	ocurrió un error inesperado
500	monto menor o igual a cero
500	no se puede procesar la validación de la tarjeta porque el usuario del servicio no está registrado