Integración de pagos recurrentes de PayU a su sistema

PayU es una de las pasarelas de pago más utilizadas en Latinoamérica, gracias a que  posee un soporte para REST API que facilita su integración con la mayoría de plataformas. En esta entrada presentaré cómo implementar una de sus funcionalidades más atrayentes:  pagos recurrentes. 

Los pagos recurrentes son el cobro automático que se realiza a una tarjeta de crédito asociada a una suscripción periódica. Esta última, configurada por cada usuario. 

Actualmente, las empresas deben facilitar la adquisición de sus productos o servicios, mediante la posibilidad de recibir pagos desde su portal web. Ello demanda protocolos de seguridad contra los fraudes en internet.

En este sentido, las plataformas de pago son agentes externos que proveen transparencia a las transacciones monetarias, porque notifican los estados de ventas y se hace carga de posibles problemas.  

A continuación , los pasos básicos para la implementación de pagos recurrentes en su sitio web. 

1. Conexión con la API de PayU

Para iniciar, conéctese con su cuenta en PayU a través de la API. Es decir, envíe una autorización básica en el encabezado «Autorización», que consta de un nombre de usuario y contraseña. 

Con dicha información en el encabezado han de realizar todas las transacciones con PayU, de lo contrario recibirá un código de error.

 

2. Creación de los planes de pago 

Luego de la autenticación, cree los planes de pago que su empresa ofrecerá, mediante un  POST request a «/payments-api/rest/v4.9/plans»: 

 

{ 
  "id de cuenta": "512321", 
  "planCode": "ejemplo-plan-code-001", 
  "description": "Plan de muestra 001", 
  "intervalo": "MES", 
  "cuentaintervalos": "1 ", 
  "maxPaymentsAllowed": "12", 
  "pagoAttemptsDelay": "1", 
  "Valoresadicionales": [ 
    { 
      "nombre": "PLAN_VALUE", 
      "valor": "20000", 
      "moneda": "COP" 
    } 
  ] 
}

 

Este ejemplo creó un plan recurrente de $20.000 al mes, asociado con la cuenta 512321, cuyo código es «sample-plan-code-001». Se cobrará durante 12 meses (maxPaymentsAllowed) y solo intentará efectuar el pago una vez, antes de cancelarse por sí misma la suscripción (paymentAttemptsDelay).

 

Si la creación es exitosa recibirá esta respuesta:

 

{ 
  "id": "b3d406d0-abd4-473c-a557-25aa81ff9032", 
  "planCode": "ejemplo-plan-code-001", 
  "description": "Plan de muestra 001", 
  "id de cuenta": "512321 ", 
  "recuento de intervalos": 1, 
  "intervalo": "MES", 
  "pagos máximos permitidos": 12, 
  "intentos de pago máximos": 0, 
  "retraso de intentos de pago": 1, 
  "pagos pendientes máximos" : 0, 
  "días de prueba": 0, 
  "Valores adicionales": [ 
    { 
      "nombre": "PLAN_VALUE", 
      "valor": 20000,
      "moneda": "COP" 
    } 
  ] 
}

 

En caso de error, será así: 

 

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

 

Cabe decir que este proceso se ejecuta solo una vez por cada plan creado. 

3. Suscripción a los aviones 

Una vez creado al menos un plan recurrente, puede suscribir a los usuarios para comenzar el débito automático . Para ello, requiere enviar un JSON con la información del cliente y su tarjeta de crédito, a través de un POST request a «/rest/v4.9/subscriptions/»: 

 

{ 
  "pago inmediato": verdadero, 
  "cuotas": 10, 
  "cliente": { 
    "fullName": "Jhon Pérez", 
    "correo electrónico": "[email protected]", 
    "tarjetas de crédito": [ 
      { 
        " nombre": "Jhon Doe", 
        "documento": "0000000001", 
        "número": "4242424242424242", 
        "expMes": 1, 
        "añoexp": 2022, 
        "tipo": "VISA" 
      } 
    ] 
  }, 
  "plan" : { 
    "codigoplan": "ejemplo-codigo-plan-001" 
  } 
}

 

Al igual que en el caso de la creación del plan recurrente , recibirá un mensaje en caso de éxito o no de la suscripción. 

Por otro lado, PayU genera en su base de datos objetos para cada tarjeta de crédito y cada cliente creado. Por esta razón, puede enviar directamente el ID de estos objetos a la hora de crear la suscripción al plan, en vez de enviar nuevamente la información. 

4. Creación de Facturas

El paso final es comprobar el cobro de la transacción.

Para obtener la facturación realizando un GET request a «/rest/v4.9/recurringBill» con alguno de los siguientes parámetros:

1. «?ClienteId={clienteId}»

Este parámetro entrega todas las facturas para el cliente de PayU. 

2. «?subscriptionId={subscriptionId}»

E ste, provee  todas las facturas para la suscripción requerida.

3. «?customerId={customerId}&dateBegin={dateBegin}&dateFinal={dateFinal}»

Este último, muestra todas las facturas requeridas en el rango de fechas dado, lo que requiere tanto del parámetro dateBegin como el dateFinal para no generar error. 

 

En cualquier caso, recibirá todas las facturas solicitadas:

 

{ 
  "lista de facturas recurrentes": [ 
    { 
      "id": "cc522b0e-af0b-4ece-978d-f5c5632caa52", 
      "ID de pedido": 71516840, 
      "subscriptionId": "6dtg51j09cr", 
      "estado": "PAGADO", 
      "cantidad": 10000, 
      "moneda": "COP", 
      "cargo de fecha": 1391490000000 
    }, 
    { 
      "id": "56f0f5ca-cf29-437e-8920-7bc35578a39f", 
      "subscriptionId": "6dtf4q8v451", 
      "estado ": "CANCELADO", 
      "cantidad": 10000, 
      "moneda":"COP", 
      "cargo de fecha": 1392786000000 
    } 
  ] 
}

 

Con estos datos puede conocer el estado de los pagos. Este paso es el que, en mi opinión, tiene más fallas desde el sistema de PayU, ya que el filtro es muy limitado por lo que cuesta determinar el pago de una factura bajo condiciones específicas. 

 

Consideraciones finales

Integrar PayU es sencillo, tanto que al utilizar REST API como método de comunicación, el formato JSON permite recibir y entregar información en cualquier lenguaje, desde una aplicación servidor o la del cliente. 

PayU podría mejorar la manera de presentar los errores de las tarjetas de crédito, por ejemplo, pero en general funciona muy bien, por lo que recomiendo leer la  documentación oficial . Esta permitirá realizar una implementación adecuada que considere factores como los errores, los tiempos de respuesta, entre otros.