enzona_payments 1.2.0

Paquete para gestionar sus pagos a través de la pasarela de pagos Enzona.

Enzona Payments (Dart)

Esta librería es un cliente Dart para interactuar con la API de Enzona desde el lado del comerciante. A continuación encontrarás una guía de uso, ejemplos y referencia rápida de los modelos incluidos.

Instalación

• Añade el paquete a pubspec.yaml de tu proyecto (o publícalo/ánclalo localmente según tu flujo).

Resumen rápido

• Constructor: MerchantInfo(consumerKey, consumerSecret) — credenciales del comercio.
• Cliente principal: Enzona — instancia creada con un MerchantInfo.
• Operaciones principales:
  • Future<Payment> createPayment(PaymentRequest request) : crea una reservación de pago.
  • Future<Payment> getPayment(String transactionUuid) : consulta el estado de una transacción.
  • Future<bool> completePayment(String transactionUuid) : completa/cierra la transacción (después del pago).
  • Future<bool> cancelPayment(String transactionUuid) : cancela la transacción.

Ejemplo de uso

import 'package:enzona_payments/enzona_payments.dart';
import 'package:enzona_payments/merchant_Info.dart';
import 'package:enzona_payments/models/product.dart';
import 'package:enzona_payments/models/details.dart';
import 'package:enzona_payments/models/payment_request.dart';
import 'package:enzona_payments/models/currency.dart';

Future<void> example() async {
  final merchant = MerchantInfo('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');
  final enzona = Enzona(merchant);

  final items = [Product(1, 'T-shirt', 'Blue T-shirt', 10.0, 0.0)];
  final details = Details(0.0, 0.0, 0.0);

  final request = PaymentRequest(
    'merchant-uuid', // merchant_uuid
    'op-id-123',     // merchant_op_id
    'Compra ejemplo',
    details,
    'https://miapp.com/return',
    'https://miapp.com/cancel',
    Currency.CUP,
    items,
    'INV-001',
    'terminal-1',
  );

  final payment = await enzona.createPayment(request);
  // Busca en payment.links el link con rel == 'confirm' y redirige al usuario.

  final updated = await enzona.getPayment(payment.transaction_uuid);
  await enzona.completePayment(payment.transaction_uuid);
  // o await enzona.cancelPayment(payment.transaction_uuid);
}

Modelos y validaciones

• PaymentRequest — campos principales: merchant_uuid, merchant_op_id, description, return_url, cancel_url, currency (Currency.CUP o Currency.CUC), items (List<Product>), invoice_number, terminal_id.
• Product — construye con Product(quantity, name, description, price, tax); valida quantity >= 1 y price > 0.
• Details — contiene shipping, discount, tip, tax; se usa para calcular el amount final.
• Payment — respuesta que incluye transaction_uuid, status_code, status_denom, price_total, items, links.

Errores y excepciones

• Excepciones principales en lib/exceptions (por ejemplo EEnzonaPayment, EEnzonaSettings). Las operaciones HTTP lanzan EEnzonaPayment en caso de fallo.

Arquitectura y archivos clave

• Cliente principal: lib/enzona_payments.dart
• Autenticación y cliente HTTP: lib/merchant_Info.dart
• Modelos: lib/models/payment_request.dart, lib/models/payment.dart, lib/models/product.dart, lib/models/details.dart
• Excepciones: lib/exceptions
• Tests: test/enzona_payments_test.dart

Notas de integración

• MerchantInfo obtiene y refresca el token (mira authenticate() en lib/merchant_Info.dart).
• createPayment devuelve un Payment con links; el link de rel == 'confirm' es el que debes abrir para que el usuario haga el pago.
• Asegúrate de manejar correctamente las redirecciones en tu app (webview o navegador) para diferenciar return_url y cancel_url.

Si quieres, puedo:

• Ejecutar los tests del paquete.
• Añadir ejemplos más completos (por ejemplo un pequeño servidor de ejemplo o widget WebView).

---

Documentación actualizada para que los desarrolladores Dart entiendan el uso del paquete.