Persilsoft.Culqi.Server 1.0.14

Persilsoft.Recaptcha.Server

Expone algunos endpoints para interactuar con la API de Culqi durante el proceso de Checkout.

Ejemplo:

Primero, se necesitan registrar los servicios que requiere el Backend:

using Persilsoft.Culqi.Shared.Options;
using ServiceCollectionExtensions;

Action<CulqiOptions> CulqiOptionsConfigurator = options =>
builder.Configuration.GetSection(CulqiOptions.SectionKey).Bind(options);
builder.Services.AddCulqiServices(CulqiOptionsConfigurator);

En el archivo de configuración appsetting.json debe configurar la siguiente entrada:

"Culqi": {
    "PrivateKey": "xxxxxxxxxxxxx",
    "WebApiBaseAddress": "https://api.culqi.com",
    "CreateOrder": "/v2/orders",
    "CreateCharge": "/v2/charges"
}

Donde:
PrivateKey: Es la llave privada proporcionada por Culqi para interactuar con sus servicios.
WebApiBaseAddress: Es la Url base de los servicios de Culqi.
CreateOrder: Es el endpoint de Culqi para crear órdenes.
CreateCharge: Es el endpoint de Culqi para crear cargos.

Para mayor información, puede consultar la documentación de la Api de Culqi en https://apidocs.culqi.com/

Una vez registrados los servicios, necesitamos agregar a la canalización de AspNet Core los endpoints que van a interactuar con la Api de Culqi:

app.UseCulqiEndpoints(requireAuthorization: false);

Nota: Si requiere proteger dichos endpoints a través de un Middleware de autenticación, deberá asignar true al argumento requireAuthorization

Ahora, ya puede probar los Endpoints. Si su WebApi tiene instalado y configurado swagger, podrá visualizarlos:

Crear cargo

Para realizar un cobro a un número telefónico vinculado con Yape o a una tarjeta de débito/crédito, es necesario crear un cargo utilizando un token o una tarjeta. Si utilizas tu llave secreta de integración no se realizarán cargos reales, a diferencia del entorno de producción donde sí se enviará la petición a los bancos y marcas procesadoras.
El objeto Json tiene la siguiente forma:

{
  "amount": 3550,
  "currencyCode": "PEN",
  "email": "juan.perez@persilsoft.com",
  "sourceId": "ype_test_IOmSg3Mue8wtYXgp",
  "capture": true,
  "description": "Por consumo en Inca Pizzas Andinas",
  "installments": null,
  "metadata": {
    "dni": null,
    "celular": null
  },
  "antifraudDetails": {
    "firstName": null,
    "lastName": null,
    "phoneNumber": null,
    "address": null
  }
}

Donde:
amount: Monto del cargo. Sin punto decimal (requerido).
currencyCode: Código de moneda en formato ISO 4217, por ejemplo PEN (requerido).
email: Correo electrónico del cliente (requerido).
sourceId: ID del objeto token, objeto Yape u objeto tarjeta que se va a usar en la creación del cargo (requerido).
capture: Indica si se va a realizar la captura automática de la tarjeta (requerido).
description: Descripción del cargo a realizarse.
installments: Cantidad de cuotas que se van a aplicar al pago. Estas dependen de las cuotas aceptadas por el objeto token.
metadata: Información adicional que se quiere enviar del cargo.
antifraudDetails: Datos de la persona que realiza la compra, para detectar posibles fraudes.

Crear orden

Este proceso permite que se genere un objeto orden con los detalles de la posible venta, la cual se crea con un estado pendiente de pago. Además, al momento de la creación tu cliente recibe un correo con las instrucciones de cómo pagar la orden.
Si una orden es creada con el parámetro confirm en false, esta tendrá que ser confirmada inmediatamente con el método Confirm orden; de los contrario, la orden no podrá ser pagada por tu cliente. Se recomienda crearla sin incluir el parámetro "confirm" para que siga el flujo natural.
El objeto Json tiene la siguiente forma:

{
  "amount": 42500,
  "currencyCode": "PEN",
  "description": "Por consumo en Inca Tratoria",
  "orderNumber": "Orden-00000001",
  "expirationDate": "1713225279",
  "clientDetails": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "juan.perez@persilsoft.com",
    "phoneNumber": "999888777"
  },
  "confirm": true,
  "metadata": {
    "dni": "12345678"
  }
}

Donde:
amount: Monto de la orden. Sin punto decimal (requerido).
currencyCode: Código de moneda en formato ISO 4217, por ejemplo PEN (requerido).
description: Descripción de la orden (requerido).
orderNumber: Número que identifica a la orden. Debe ser único (requerido).
expirationDate: Fecha de expiración de la orden. Debe ser una fecha futura (requerido).
clientDetails: Datos de la persona que realiza la compra (requerido).
confirm: Indica si se debe confirmar la orden (requerido).
metadata: Informacion adicional que se requiera enviar al crear la orden. Ejemplo: "{dni":"12345678"}.

Si ocurre un error al crear un cargo o una orden se lanzará una excepción CreateCulqiChargeException o una excepción CreateCulqiOrderException según sea el caso.
Usted puede implementar un manejador de excepciones personalizado para manejar estas excepciones y formatear la respuesta de manera apropiada o puede registrar los manejadores de excepciones incluidos en este paquete. Adicionalmente, puede agregar el manejador para atrapar cualquier otra excepción no controlada.

builder.Services
    .AddCulquiExceptionHandlers()
    .AddUnhandledExceptionHandler();

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var SupportedCultures = new[] { "es-PE", "en-US" };
    var NeutralCulture = SupportedCultures[0];

    options.SetDefaultCulture(NeutralCulture)
    .AddSupportedCultures(SupportedCultures)
    .AddSupportedUICultures(SupportedCultures)
    .ApplyCurrentCultureToResponseHeaders = true;
});

Luego, incluirlos a la canalización de su aplicación AspNet Core.

app.UseRequestLocalization();
app.UseExceptionHandler(builder => { });

Tenga en cuenta que si decide utilizar los manejadores de excepción proporcionados por el paquete, será necesario configurar el middleware de localización. Observe que el middleware de localización se agrega antes que el middleware para manejo de excepciones.