Notificación de Pagos (IPN)

IPN es un servicio de mensajería que permite a los comercios deTotal Coin recibir notificaciones instantáneas de los pagos recibidos e integrar TotalCoin con su administrador de cobros. Este servicio permite además consultar el estado de los pagos en cualquier momento.

Sistema de notificacion de pagos

Introducción

IPN es un servicio de mensajería que permite a los comercios de TotalCoin recibir notificaciones instantáneas de los pagos recibidos e integrar TotalCoin con su administrador de cobros. Este servicio permite además consultar el estado de los pagos en cualquier momento.

Funcionamiento

IPN es un servicio de consulta a través de mensajes. El comercio que lo utilice, deberá asignar una URL de su propio servidor que servirá como receptor de notificaciones en formato JSON. Este deberá estar preparado para recibir e interpretar la información de las transacciones en este formato.

  • TotalCoin enviará las notificaciones automáticas a esa URL o Receptor cada vez que ocurra un evento o cambio relacionado a un pago recibido del comercio.

  • LA URL o Receptor debe estar siempre disponible para recibir y procesar mensajes, ya que estos pueden ser enviados en cualquier momento.

Ejemplo de botón de pago

  1. Comprador hace click en el Botón de Pago del comercio (vendedor).

  2. El servidor de TotalCoin le informa al comercio que ha ocurrido la transacción

  3. El comercio pide a TotalCoin los datos de la transacción.

Podrá ser utilizado tanto para administrar las operaciones como para recibir información detallada sobre una determinada transacción:

  • Historial de estados de la misma con su fecha y hora

  • Monto total abonado

  • Comisión debitada

  • Monto neto recibido

  • ID de la transacción

  • Nombre del cliente

  • Referencia

Habilitación de servicio

Procedimiento

  1. El usuario ingresa a su cuenta TotalCoin y se dirige a la Sección "Mi cuenta/Mis Comercios". Allí podrá ver un listado de sus comercios, agregar nuevos y editar sus nombres. Cada comercio tiene asignado un Identificador único (ME).

    Nota: Al crearse un usuario, el sistema le otorga un comercio por default, que no podrá eliminarse, ya que todas las transacciones relacionadas con ventas deben estar relacionadas a un comercio de este. Asimismo, los comercios creados que posean transacciones y botones o solicitudes de pago asociadas tampoco podrán ser eliminados.

  2. Se dirige a la sección "Mi cuenta/Notificaciones de Pago (IPN)". El sistema muestra un listado de sus comercios con sus respectivos identificadores indicando si poseen o no habilitado el servicio de IPN, sus URLs receptoras asociadas en caso de poseer habilitado el servicio, y un ícono de edición para cada uno, desde donde podrá habilitar o deshabilitar el servicio de IPN para los mismos:

  3. Selecciona el ícono de Editar del comercio para el cual desea habilitar el servicio.

  4. Una vez allí setea "IPN Habilitado" en "Sí"" e ingresa la URL de su sitio que servirá como página receptora de notificaciones.

  5. Ingresa su PIN y Confirma

    TotalCoin enviará una notificación a la URL receptora del comercio y esperará recibir como respuesta un HTTP Status Code 200 para darla como habilitada, de manera de verificar que ésta URL este apta para recibir notificaciones. Caso contrario no la guardará y le informará de esto al usuario.

Diagrama de funcionamiento

Caso exitoso de notificación

Configuración de la API

Notificaciónes de pago mediante URL

Las notificaciones de pago pueden ser recibidas en una URL, que el usuario debe configurar previamente, desde su cuenta TotalCoin en la sección "Mi cuenta"/"Comercios".

TotalCoin informa por GET al usuario cuando un pago se registra o cambia de estado, con dos parámetros: reference, que es el identificador o número de referencia de la transacción, y merchant reference, que es el identificador del producto dentro del comercio del usuario, en caso de existir. Por ejemplo:

reference = 0000000012
merchant reference = CODIGO123

Si la URL de respuesta configurada por el usuario es:

http://www.misitio.com/notificaciones

Recibirá por get las notificaciones de la siguiente manera:

http://www.misitio.com/notificaciones/?reference=0000000012&merchant=CODIGO123

TotalCoin informará del registro o cambio de estado del pago hasta que el servidor del usuario confirme que lo recibió (debe responder HTTP Status Code 200), o se agote el número de reintentos, siguiendo el siguiente esquema:

  • Reintento N°1: A los 5 minutos

  • Reintento N°2: A los 45 minutos

  • Reintento N°3: A las 6 horas

  • Reintento N°4: A los 2 días

  • Reintento N°5: A los 4 días

Consulta de los pagos notificados

El comercio podrá consultar a IPN para obtener la información específica de la transacción o transacciones notificadas.

Para consultar la información del pago que TotalCoin acaba de notificarle, el webservice del usuario debe enviar una solicitud GET a la URL de notificación de TotalCoin, incluyendo en la URL el ApiKey, que es el identificador único del usuario y el parámetro reference, ID de la operación que recibió en la URL de notificación.

Request Curl

curl -X GET \
-H 'accept: application/json' \
'https://api.totalcoin.com/ar/Ipn/CDFE6CE9-2D91-47FE-AA23-BAD479E4F615/0000000019'

Response

Status code: 200 OK
{
  "Transaction": {
    "Reference": "0000000019",
    "MerchantReference": "Raqueta Super Pro XXL3213",
    "TransactionType": "Sale",
    "Reason": "Raqueta Super Pro XXL3213",
    "Currency": "ARS",
    "PaidAmount": 5900,
    "NetAmount": 5612.73,
    "FinancingCost": 0.00,
    "TotalAmount": 5900.00,
    "TransactionHistories": [
      {
        "Date": "2015-05-21T23:48:04.72",
        "TransactionState": "InProccess"
      },
      {
        "Date": "2015-05-21T23:48:09.08",
        "TransactionState": "Approved"
      }
    ],
    "Merchant": {
      "Id": "5fab1cac-ba84-4765-8ef7-5977badcc907",
      "Name": "Comercio Predefinido"
    },
    "FromUser": {
      "Phone": "1144690168",
      "FullName": "Mauro Zuccolo",
      "Email": "maurozuccolo@gmail.com"
    },
    "ToUser": {
      "Phone": "1143214321",
      "FullName": "TEST VIEWSTORMING",
      "Email": "tomas@viewstorming.com"
    },
    "Provider": {
      "Name": "TOTALCOIN",
      "PaymentMethod": "TotalCoin"
    }
  },
  "IsResponseOk": true,
  "Message": null
}
                            

Estados de las operaciones

Los posibles estados que puede tomar una transacción y entre los que puede cambiar son los siguientes:

  • InProcess: Es todo estado de verificación previo a la confirmación del pago o movimiento de dinero entre cuentas por parte de la/s entidad/es correspondiente/s.

  • Approved: El pago fue informado a TotalCoin como aprobado por la/s entidad/es correspondiente/s.

  • Available: El dinero de la transacción realizada se ha acreditado y/o debitado en las cuentas correspondientes.

  • Rejected: La transacción no ha llegado a acreditarse en tiempo y forma por algún error de comunicación, falta de pago o impedimento legal.