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 2xx (por ejemplo, 200 o 201). Si no la recibimos, reintentaremos de nuestro lado: la notificación se entrega hasta 3 veces en total, con una espera de aproximadamente 2 minutos entre cada intento. Si tras esos intentos no obtenemos una respuesta exitosa, dejamos de reintentar.

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",
        "baseAmountPayed": "100.00",
        "paymentMethod": "Visa Debito",
        "status": "approved",
        "paymentDate": "2020-11-17",
        "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",
        "baseAmountPayed": "100.00",
        "paymentMethod": "Visa Debito",
        "status": "approved",
        "paymentDate": "2020-11-17",
        "message": null,
        "estimatedAccreditationDate": "2020-11-20",
        "paymentId": 46858
    },

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

baseAmountPayed (monto base pagado, sin recargos) y paymentDate (fecha del pago) se incluyen cuando la factura está pagada.

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"
}

url debe ser una URL http/https válida y única dentro de tu organización: si ya configuraste esa misma URL, el alta falla (The URL already exists in the configuration).