SDK de HtechPay Flutter

Descripción

El siguiente SDK te ayudará a integrar de una manera rápida la carta de pago de HtechPay en aplicaciones móviles hechas en Flutter.

Para utilizar el sdk flutter HtechPay en tu proyecto deberas primero agregar la de dependencia en tu archivo pubspec.yaml.

htech_pay

Deberas importarla en tu archivo .dart donde deseas que el proceso de cobro se inicie:

import 'package:htech_pay/htech_pay.dart';

Crear una instancia de la clase HtechPay

final htechPay = HtechPay();

📘

Nota importante

El sdk por default esta en modo Sandbox lo que te permite realizar pruebas antes de pasar al ambiente de produccion, para pasar al ambiente de produccion con cobros reales deberas crear la instancia con la bool isSandboxMode en false.

Kotlin

final htechPay = HtechPay(isSandboxMode: false);

Generando un pago

Antes de ejecutar la función makePayment que te permite realizar el cobro necesitaras generar un orderId que contiene la información de la transacción. Una vez que tengas un orderId, ejecuta la función makePayment para iniciar el proceso de venta.

  void makePaymentByNewCard() async {
  
    final orderId = await ApiBackend.getOrderId(
      customerId,
      amount,
      description,
    );
    final htechPay = HtechPay();

    htechPay
        .makePayment(
          orderId: orderId,
          context: context,
          isDarkTheme: widget.isDarkTheme,
        )
        .then((response) {
          processResponse(response);
        })
        .onError((error, stack) {
          showErrorResponse();
        });
  }

Ademas del orderId, la funcion solicita el contexto de donde se lanzara la vista de la carta de pago.

Respuesta

La función regresa un objecto de tipo HtechPayResponse que contiene el resultado de la transacción, si fue o no exitosa y en caso de ser exitosa, contiene información del pago.

HtechPayResponse

payload

Pago con tarjeta guardada

Para realizar un pago con una tarjeta almacenada previamente se requiere enviar al backend el token de la tarjeta en la peticion begin-transaction para obtener el orderId para posteriormente invocar la funcion makePaymentByToken.

void makePaymentByToken(String token) async {
  
  final orderId = await ApiBackend.getOrderIdByTokenCard(
      customerId,
      token,
      amount,
      description,
    );
  final htechPay = HtechPay();

  htechPay
      .makePaymentByToken(orderId: orderId, context: context, isDarkTheme: true)
      .then((response) {

        processResponse(response);
      })
      .onError((error, stack) {
        
        showErrorResponse();
      });
}

Respuesta

La función regresa un objecto de tipo HtechPayResponse que contiene el resultado de la transacción, si fue o no exitosa y en caso de ser exitosa, contiene información del pago, es la misma respuesta que la función makePayment.

Guardar una tarjeta

Para guardar una tarjeta y relacionarla con un customer, deberás solicitar un orderId mediante una llamada backend a begin-transaction-create-card y posteriormente invocar la funcion saveCard.

  void addNewCard() async {
    final requestId = await ApiBackend.getRequestId(customerId);
    debugPrint("RequestId $requestId");

    htechPay
        .saveCard(orderId: requestId, context: context, isDarkTheme: true)
        .then((response) {
          debugPrint("Response save card success? $response");

          setState(() {});
          if (!response) {
            showErrorToAddNewCard();
          }
        })
        .onError((error, stack) {
          debugPrint("Error al guardar tarjeta, ${error.toString()}");
          showErrorToAddNewCard();
        });
  }

Pago con tarjeta nueva usando Widget.

Para realizar un pago mediante el widget HtechPayCardFieldWidget deberas agregarlo a tu arbol de vistas y crear una clase tipo controller para manipular sus acciones.

En tu arbol de vistas Instancia el Widget.

                    ...
                    SizedBox(height: 8.0),
                    HtechPayCardFieldWidget(
                      orderId: widget.orderId,
                      controller: _paymentFieldController,
                      type: CardFieldType.widget,
                      onPaymentResult: (HtechPayResponse response) {
                        setState(() {
                          _isInitPaymentProcess = false;
                        });

                        Navigator.pop(context, response);
                      },
                      onValidForm: (bool isValidForm, ErrorsForm errors) {
                        if (isValidForm) {
                          processPayment();
                          return;
                        }

                        debugPrint("""
                          Card-number isError? : ${errors.numCard}
                          Card-date is isError? : ${errors.date}
                          Card-cvv is isError? : ${errors.cvv}
                        """);

                        setState(() {
                          _isInitPaymentProcess = false;
                        });
                      },
                      onError: (errorMessage) {
                        setState(() {
                          _isInitPaymentProcess = false;
                        });
                        debugPrint("Error $errorMessage");
                      },
                      onProcessPayment: () {
                        debugPrint("onProcessPayment");
                      },
                      on3dsChallengeOpen: (bool isOpen) {
                        if (isOpen) debugPrint("Showing 3ds challenge!!");
                      },
                      onGetWidgetStatus: (CardFieldWidgetStatus status) {
                        switch (status) {
                          case CardFieldWidgetStatus.start_loading:
                            debugPrint("Start loading widget");
                          case CardFieldWidgetStatus.finish_loading:
                            debugPrint("Finish loading widget");
                        }
                      },
                      onClose: () {
                        debugPrint("onClose");
                        Navigator.pop(modalSheetContext);
                      }
                    ),
                    SizedBox(height: 8.0)
                    ...

A continuación se enlistan los atributos requeridos y opcionales para que el widget pueda funcionar correctamente.

Atributos requeridos u obligatorios:

• isSandboxMode: Bool para indicar el modo en el que el Widget deberá comportarse, por default este parametro es true, indicando que el Widget estará en modo desarrollo o pruebas, una vez que se probo y funciona, para ser usado en producción esta variable deberá estar como false. Nota: para identificar rapidamente si el widget se encuentra en modo desarrollo o pruebas, visualmente el widget contendrá una leyenda en rojo o amarillo.
• orderId: Es el identificador de la transacción, se obtiene a traves de una petición backend to backend, contiene información necesaria para la transacción como lo es el monto.
• controller: Es la clase controladora del Widget, deberas crear una instancia y agregarla como parametro. Esta clase te permitira realizar las acciones como validar el formulario o iniciar el proceso del payment (Se describe mas adelante).
• type: Es un enum tipo CardFieldType para identificar el tipo de Widget que se desea mostrar, de acuerdo al tipo del widget se comportara y se mostrara de diferente forma, estas son los diferentes tipos:
  • widget : Pago con tarjeta nueva y la UI de tipo CardField.
  • paymentTokenWidget: Pago con tarjeta guardada o token y la UI de tipo CardField.
  • paymentToken : Pago con tarjeta guardada o token y UI de tipo Modal, Fullscreen.
• onPaymentResult: Es la función que retornara la respuesta del pago, contiene el objeto HtechPayResponse con la información de la respuesta del pago.
• onValidForm: Es la función que retorna la respuesta ante la acción de validar el formulario de pago, es decir desde el controller se podrá invocar una función para validar unicamente la información de la tarjeta, la respuesta sera devuelta en esta función, esta función contiene los siguientes objetos:
  • bool (isValidForm) : Variable de tipo bool indicando si el formulario de pago contiene datos de tarjetas validos (isValidForm = true) o no (isValidForm = false).
  • ErrorsForm (errors): Objeto que contiene los campos de la tarjeta que no son correctos ya sea el numero de tarjeta, la fecha de expiración o el código cvv, en caso de que isValidForm sea true, este objeto deberá ser omitido.
• onError: Es la función que indicara si hubo un error durante la inicialización del widget. retorna un valor tipo String con la descripción del error.

Atributos opcionales:

• onProcessPayment: Esta función sirve de aviso al desarrollador de que el Widget ha iniciado el procesamiento del payment, esta función es disparada por el Widget una vez que desde el controller se ejecutado el metodo processPayment.
• on3dsChallengeOpen: Esta función sirve de aviso al desarrollador que el Widget deberá mostrar el reto de 3ds para poder procesar de manera correcta el payment, A continuación el widget tomara el control de la vista y mostrara el reto de manera fullScreen, esto con la finalidad de facilitar al tarjetaambiente la autorización del payment. Como parametro esta función contiene una variable tipo bool (isOpen) indicando como true cuando el reto sera mostrado, y como false cuando el reto ha sido finalizado y se cerrara la vista fullscreen.
• onGetWidgetStatus: Esta función sirve de aviso al desarrollador los diferentes estatus que el widget presente, devuelve una variable de tipo enum con los siguientes valores:
  • start_loading : Estatus que se dispara cuando el widget se instancia y empieza a cargar de manera interna los componentes.
  • finish_loading: Estatus que se dispara cuando ha finalizado de cargar los componentes internos.
• isDarkTheme: bool que sirve para indicar que el Widget debe mostrar la UI en tema dark. por default este parametro viene como false.
• onClose : Esta función sirve de aviso al desarrollador que el Widget sera cerrado y desmontado, por lo que sirve de aviso para que en tu flujo la vista del widget tambien sea cerrada, la acción que dispara esta función es el boton “Cancelar” dentro del widget de pago con token cuando el type sea paymentToken.

Controller.

HtechPayPaymentFieldController.

Esta es la clase controladora que el widget necesita como parametro para operar de manera correcta, basta con instancia una variable antes de mostrar el Widget en tu árbol de vistas, puede ser en el metodo initState.

final HtechPayPaymentFieldController _paymentFieldController =
    HtechPayPaymentFieldController();

Desde el controller, tienes acceso a las siguientes dos apis:

• validateForm : Función que dispara el proceso de validación de los datos de tarjeta que se ingresaron en el Widget, esta función te sirve para validar que los datos de la tarjeta son ingresados correctamente. Esta funcion devuelve el resultado de la validacion en la funcion onValidForm: (bool isValidForm, ErrorsForm errors) del Widget, donde:
  • isValidForm : Variable bool donde true = datos de la tarjeta validos y correctos, false = existe al menos 1 dato que no es correcto o su validación fue incorrecta.
  • errors : Este objeto es de tipo ErrorsForm, cuando isValidForm sea false, este objeto te devolvera que dato(s) de la tarjeta son los incorrecto, ya sea el numero de tarjeta, la fecha de expiracion o el cvv.
• processPayment: Función que dispara el proceso para iniciar el pago, Si los datos de la tarjeta ingresada son correctos, esta función iniciara el proceso para pagar, al iniciar el proceso podras seguir el proceso, las validaciones y la respuesta en los siguientes callbacks del widget:
  • onProcessPayment
  • on3dsChallengeOpen
  • onClose
  • onError
  • onPaymentResult