En la actualidad, es una necesidad creciente entre las empresas ofrecer la posibilidad de realizar pagos directamente a través de su portal web a sus usuarios. Sin esta posibilidad, la adquisición de productos o servicios ofrecidos por dicha empresa es engorrosa, lenta e inusable por una gran parte del mercado; lo que se resume en una pérdida de compradores potenciales significativa. Ahora bien, brindar esta posibilidad no solo requiere una implementación adecuada sino que también requiere contar con determinados protocolos de seguridad para garantizar que ni la empresa ni el consumidor serán víctimas de la gran cantidad de fraudes que a diario suceden en la web, entre otros problemas que se pueden presentar.

Con el fin de facilitar el proceso de pagos a través de internet así como de garantizar seguridad y confianza tanto a la empresa como al consumidor, existen las pasarelas de pago; cuyo fin es encargarse de todos los procesos relacionados con dinero. Simplemente, el consumidor paga a través de dicha pasarela de pago, esta informa a la empresa el estado de la transacción realizada y la empresa entrega el producto o el servicio al consumidor dependiendo de dicho estado. En caso de haber algún problema con el dinero, es la pasarela de pago la responsable; lo que simplifica los procesos internos de la empresa y le da tranquilidad tanto a esta como al consumidor al haber un agente externo encargado de la transparencia de la transacción.

Una de estas pasarelas de pago es PayU, ampliamente utilizada en latinoamérica. Como todas las pasarelas de pago, tiene sus ventajas y sus desventajas; su uso depende de las necesidades de su negocio de recibir pagos via web así como la facilidad de integrar dicha pasarela con su plataforma. En el caso de PayU, poseen soporte para REST API lo que facilita su integración con la mayoría de plataformas. Precisamente, en esta entrada discutiré brevemente cómo utilizar este soporte para implementar una de las funcionalidades de PayU más atrayentes: Los pagos recurrentes.

En resumidas cuentas, un pago recurrente es una subscripción que automáticamente realizará un cobro a la tarjeta de crédito asociada a dicha subscripción periódicamente; siendo este periodo configurable cuando se crea o se edita la subscripción. Para integrar esta funcionalidad con nuestro sitio, se debe considerar lo siguiente.

Conexión con la API de PayU

Para poder conectarse con su cuenta en PayU a través de la API, debe enviar una autorización básica en el header “Authorization” que consta de un username, en este caso el API Login de su cuenta, y un password, que corresponde al API Key de su cuenta. Con esta información en el header, se han de realizar todas las transacciones con PayU o sino recibirá un código de error de autenticación.

Creación del plan

Luego de tener el proceso de autenticación, se han de crear los planes que su empresa va a ofrecer. Para esto, se debe realizar un POST request a “/payments-api/rest/v4.9/plans” Por ejemplo:

{
  "accountId": "512321",
  "planCode": "sample-plan-code-001",
  "description": "Sample Plan 001",
  "interval": "MONTH",
  "intervalCount": "1",
  "maxPaymentsAllowed": "12",
  "paymentAttemptsDelay": "1",
  "additionalValues": [
    {
      "name": "PLAN_VALUE",
      "value": "20000",
      "currency": "COP"
    }
  ]
}

En este caso, se está creando un plan recurrente que cobrará $20000 mensualmente, que está asociado con la cuenta 512321 y cuyo código es “sample-plan-code-001”. Este plan se cobrará durante 12 meses y luego se cancelará (maxPaymentsAllowed) y solo se intentará efectuar el pago una vez antes de cancelar la subscripción (paymentAttemptsDelay). No es necesario para esta entrada describir el resto de la información, pero es fácilmente deducible al ver el JSON.

Si la creación fue exitosa, recibirá una respuesta similar a la que se muestra a continuación:

{
  "id": "b3d406d0-abd4-473c-a557-25aa81ff9032",
  "planCode": "sample-plan-code-001",
  "description": "Sample Plan 001",
  "accountId": "512321",
  "intervalCount": 1,
  "interval": "MONTH",
  "maxPaymentsAllowed": 12,
  "maxPaymentAttempts": 0,
  "paymentAttemptsDelay": 1,
  "maxPendingPayments": 0,
  "trialDays": 0,
  "additionalValues": [
    {
      "name": "PLAN_VALUE",
      "value": 20000,
      "currency": "COP"
    }
  ]
}

En caso contrario, recibirá un mensaje con la descripción del error. Por ejemplo:

{
  "type": "BAD_REQUEST",
  "description": "El plan con el código [sample-plan-code-210] ya existe para el comercio [508029]"
}

Cabe constatar que este proceso es necesario ejecutarlo solo una vez por plan creado.

Subscripción a un plan

Una vez creado al menos un plan recurrente, ya se pueden suscribir usuarios para empezar el débito automático cuanto antes. Para esto, se requiere enviar un JSON con la información del cliente y de la tarjeta de crédito a usar a través de un POST request a “/rest/v4.9/subscriptions/”. Por ejemplo:

{
  "immediatePayment": true,
  "installments": 10,
  "customer": {
    "fullName": "Jhon Doe",
    "email": "doe@example.org",
    "creditCards": [
      {
        "name": "Jhon Doe",
        "document": "0000000001",
        "number": "4242424242424242",
        "expMonth": 1,
        "expYear": 2022,
        "type": "VISA"
      }
    ]
  },
  "plan": {
    "planCode": "sample-plan-code-001"
  }
}

Al igual que en el caso de la creación del plan recurrente, se recibirá un mensaje con la descripción de la subscripción en caso de éxito y un mensaje con la descripción del error en caso contrario. En cualquiera de los dos casos el usuario recibirá un correo de PayU con el detalle de la transacción realizada.

Por otro lado, vale la pena dejar constancia que PayU genera en su base de datos objetos para cada tarjeta de crédito y cada cliente creado. Por esta razón, se puede enviar directamente el ID de estos objetos a la hora de crear la suscripción al plan en vez de enviar de nuevo toda la información, como en el ejemplo anterior. Estos ID vienen dentro de la respuesta obtenida en caso de haber realizado una subscripción exitosa para ser guardados en su base de datos en caso de que su sistema lo requiera.

Facturas

El paso final es comprobar el cobro de la transacción para validar que en efecto el dinero fue debitado. Para obtener la información de facturación, se debe realizar un GET request a “/rest/v4.9/recurringBill” con alguno de los siguientes parámetros:

1. “?customerId={customerId}”, retorna todas las facturas para el custumer de PayU requerido.
2. “?subscriptionId={subscriptionId}”, retorna todas las facturas para la subscripción requerida.
3. “?customerId={customerId}&dateBegin={dateBegin}&dateFinal={dateFinal}”, retorna todas las facturas para el costumer requerido en el rango de fechas dado. Vale la pena recalcar que requiere tanto del parámetro dateBegin como el dateFinal; si estos no son suministrados, el sistema de PayU retorna un error.

En cualquiera de estos casos, recibirá de respuesta un arreglo con todas las facturas relacionadas a la petición:

{
  "recurringBillList": [
    {
      "id": "cc522b0e-af0b-4ece-978d-f5c5632caa52",
      "orderId": 71516840,
      "subscriptionId": "6dtg51j09cr",
      "state": "PAID",
      "amount": 10000,
      "currency": "COP",
      "dateCharge": 1391490000000
    },
    {
      "id": "56f0f5ca-cf29-437e-8920-7bc35578a39f",
      "subscriptionId": "6dtf4q8v451",
      "state": "CANCELLED",
      "amount": 10000,
      "currency": "COP",
      "dateCharge": 1392786000000
    }
  ]
}

Con esta información, es sencillo determinar el estado de los pagos de los clientes. Este paso es el que, en mi opinión, tiene más fallos desde el sistema de PayU. El problema radica en que su filtro es muy limitado por lo que puede ser engorroso determinar el pago de una factura bajo unas condiciones específicas. Aun así, para un caso de uso normal esta parte del sistema de PayU es efectivo.

Consideraciones finales

Como se puede ver, realizar la integración de su sistema con los pagos recurrentes de PayU es bastante sencillo puesto que, al utilizar REST API como método de comunicación, utiliza el formato JSON, para recibir y entregar la información. Esto hace que implementar la integración en cualquier lenguaje, desde una aplicación servidor o una cliente, no requiera mayores consideraciones ni implementaciones complicadas. Aunque tiene algunos detalles que podrían ser mejores (por ejemplo, los errores de las tarjetas de crédito no vienen organizados y el formato de entrega no es el mismo si hay un error que si hay varios errores) PayU ofrece un método sencillo y seguro que vale la pena aprovechar para darle este tipo de servicio a los clientes de su empresa.

Finalmente, vale la pena aclarar que este post es solo un abrebocas del proceso de integración con PayU y que es necesario leer la documentación oficial para poder realizar una implementación adecuada y que considere factores como los errores, los tiempos de respuesta, entre otros.