IPN

Conceptos Generales

IPN: Instant payment notification (Notificación instantánea de pago).

Cada vez que se intente procesar un pago, Zenrise enviará una notificación del evento para poder recibirla y registrar del lado de su servidor el pago como exitoso o como fallido.

Actualmente enviamos las notificaciones instantáneas de pagos ante los siguientes eventos:

• Se realiza un pago desde el checkout externo y el mismo es exitoso o falla.
• Se intenta procesar un pago recurrente de una suscripción y el mismo es exitoso o falla.
• Se realiza un pago desde una implementación con nuestro sdk-js y el mismo es exitoso o falla.
• Se autoriza una solicitud de DEBIN.

Importante! Para cualquiera de estos casos, esperamos desde su servidor una respuesta 200 o 201. En caso de recibir cualquier otro código HTTP distinto de 200 o 201, marcaremos esa notificación como errónea y la reintentaremos cada 15 minutos hasta recibir un 200 o 201, con un máximo de 50 intentos, de nuestro lado.

Funcionamiento del IPN

Nuestra IPN envía un payload muy simple con los ids del evento a investigar. La idea es que cuando nuestra IPN llegue a su servidor, este dispare otra consulta a nuestra API para obtener más información del evento.

Este es un ejemplo de payload que recibirá de nuestra IPN

{
  "transactionId": "string",
  "invoiceId": "long",
  "externalReference": "string",
}

transactionId Identificador de la transacción que produjo este pago

invoiceId Identificador del Cupón/Factura que fue pagada (Recordar que las solicitudes de cobros generan Invoice a pagar)

externalReference El id externo de su sistema que fue enviado para esta transacción

Consulta de datos una vez recibido el IPN

Una vez que su servidor recibe nuestra notificación usted sabe que algo pasó con esa transacción, pero le falta información del detalle de la misma. Es por eso que, con los IDs que le proporcionamos, usted podrá realizar la consulta en ese momento o, si de su lado tiene un proceso más largo, puede generar un sistema de colas con nuestras IPN para ir procesando las transacciones en los momentos que a usted le convengan.

El endpoint para realizar la consulta es el siguiente, donde en invoiceId se envía el invoiceId recibido por nuestro IPN

URL : /v1/invoices/transaction/{invoiceId}

Método : GET

Requiere autorización : Sí, ver Autenticación

Respuesta

{
    "currency": {
        "name": "Peso Argentino",
        "id": 1
    },
    "date": "2020-11-17",
    "id": 129213,
    "status": {
        "id": 2,
        "name": "Paid"
    },
    "description": "SUSCRIPCIÓN MENSUAL - default Plan - NOVIEMBRE/2020",
    "organizationId": 37,
    "organization": {
        "name": "nfiorito",
        "id": 37,
        "email": null,
        "phone": null,
        "logo": null
    },
    "externalReference": "",
    "amountRemaining": "0.00",
    "firstDueDate": "2020-11-27",
    "secondDueDate": "2020-12-12",
    "amountDue": "100.00",
    "amountPaid": "100.00",
    "renderUrl": "https://render.zenrise.io/zen/invoice-pdf/p/57RBdyMGzk",
    "transactionResponse": {
        "amountPayed": "100.00",
        "paymentMethod": "Visa Debito",
        "status": "approved",
        "message": null,
        "estimatedAccreditationDate": "2020-11-20",
        "paymentId": 46858
    },
    "contact": {
        "fullName": "CARDETTI, GABRIEL",
        "id": 42814,
        "document": {
            "number": "23376285049",
            "documentType": {
                "name": "CUIT"
            }
        },
        "username": "cardettigabriel.42814",
        "password": "cardettigabriel.42814",
        "note": null,
        "externalReference": "40572831",
        "email": "gabriel@zenrise.io"
    },
    "payments": [
        {
            "date": "2020-11-17",
            "amount": "100.00",
            "paymentStatus": "ACCREDITED",
            "paymentMethod": "Visa Debito"
        }
    ]
}

El dato más relevante a revisar es el objeto transactionResponse

    "transactionResponse": {
        "amountPayed": "100.00",
        "paymentMethod": "Visa Debito",
        "status": "approved",
        "message": null,
        "estimatedAccreditationDate": "2020-11-20",
        "paymentId": 46858
    },

Analizando el mismo tendremos el resultado de la transacción con su status.

Los distintos status que nuestra API maneja para las notificaciones de pago son los siguientes:

Status	Descripción
approved	Transacción aprobada exitosamente.
pending	Transacción pendiente de pago.
rejected	Transacción fallida, el pago no se pudo procesar.
refunded	Transacción reembolsada al cliente.
chargeback	Transacción revocada, el cliente ha disputado el cargo.

Configuración de URLs a ser notificadas por nuestro IPN

Para configurar tu URL para ser notificada por nuestra IPN, simplemente enviar estos datos:

URL : /v1/ipn

Método : POST

Requiere autorización : Sí

{
"active": true,
"url": "https://url-notificaciones.com/zenrise-ipn"
}