Notificacion webhook

Este componente debe ser construido por el comercio para que reciba los datos de notificación de la transacción.

Debes tener en cuenta los siguientes pasos:

1.Debes crear un Webhook sin autenticación .

2.La Url creada será la que envies en todas las peticiones al momento de generar el recurso de pago en el campo "WebhookUrl" . Es importante tener en cuenta que si por alguna razon cambias el webhook debes modificar las url que envias en cada recurso generado.

3.Se debe generar una firma que validará la integridad de los mensajes enviados al webhook y se deben concatenar los campos de la siguiente manera:

HASH_KEY =Este dato deberá ser solicitado al area de soporte

let signature = referenceId-resourceId-amount-updatedAt-HASH_KEY; signature = crypto.createHmac("sha1", HASH_KEY).update(signature).digest("hex");

Ejemplo de respuesta que llegará a tu Webhook

Response

{
  "realAmount": 20000,
  "amount": 19405,
  "cost": "$595.00",
  "referenceId": "38**",
  "moduleId": 9,
  "productId": 117,
  "referenceKey": "3538d790-ae14-11ed-be2d-4d9b1bc987e6",
  "paymentMethod": "PSE",
  "userId": 189067,
  "resourceId": "10024**",
  "updatedAt": "2023-02-16 11:11:55",
  "providerId": 8,
  "providerReference": "3122330",
  "reference1": "435sdfsd**",
  "reference2": {
    "Label": {
      "Information": "Por seguridad algunos datos se encuentran cifrados",
      "Name": "L**A",
      "Email": "l**am@**",
      "CellPhone": "3**4",
      "DocumentType": "C",
      "DocumentNumber": "52019859",
      "Description": "Abono",
      "Commerce": "Skandia",
      "Reference1": null,
      "Reference2": null,
      "Reference3": null
    },
    "Data": {
      "ConciliationCode": "FCO",
      "ConciliationContract": "1277840",
      "DocType": "N",
      "DocNumber": "800194363"
    },
    "returnUrl": "https://www.google.com/"
  },
  "bankId": "1022",
  "bankName": "BANCO UNION COLOMBIANO",
  "status": 2,
  "sign": "aa2f472ad7e84524a02d1716b56fc16ec2a87***",
  "error": {
        "code": "20-07A",
        "message": "Error técnico en Lambda"
      }
}

• Dentro del webhook se envía el objeto "error" que muestra el "code" y "message" del error asociado a rechazos recibido por parte del proveedor / entidad bancaria o a cancelación de la transacción cuando no se completa la generación del recurso

• Los códigos de error se imprimen cuando la transacción queda Rechazada por parte de la entidad bancaria o cuando queda Cancelada debido a que no se pudo completar la generación del recurso

Notificación para Dispersión

Para las dispersiones, se enviará una notificación al webhook proporcionado en la solicitud. Esta notificación seguirá la estructura mencionada anteriormente e incluirá adicionalmente los datos del retiro. A continuación, se presenta un ejemplo:

{
    ..."webhook",
    "withdraw": {
        "id": "1403**",
        "transactionId": "5690**",
        "userId": 189067,
        "providerReference": "3122330",
        "accountNumber": "3051000002",
        "accountId": null,
        "createdAt": "2023-02-16 11:10:55",
        "updatedAt": "2023-02-16 11:12:55",
        "deletedAt": null,
        "infoReference": "435sdfsd**",
        "observation": null
    },
}

Para realizar una simulación de la notificación del webhook podrás enviar la siguiente petición con los datos de una transacción que hayas realizado.

La implementación del webhook por parte del usuario API es de carácter obligatorio. Se debe asegurar la recepción y almacenamiento de la información para el proceso de conciliación por parte del usuario API con RefácilPay.

Este ítem será evaluado durante el proceso de certificación y será obligatorio para el proceso de paso a Producción

Estructura y ejemplo de petición del webhook

POST https://pay-api.qa.refacil.co/webhook/notify

Request Body

Name	Type	Description
amount*	Integer	Valor total de la transacción
cost*	Integer	costo de la transacción
Resource	Object	Objeto
id	Integer	Identificador del recurso de pago
updatedAt	String	Fecha y hora en la cual se procesó la transacción
status*	Object	identificador estado de la transaccion
id*	String	ID del estado de la transacción : 1 Pendiente , 2 Aprobada ,3 Fallida
id *	Integer	identificacion de la transaccion
description	String	Detalle del estado
Key	interger	llave
PaymentMethod	Object	metodo de pago
id	String	identificador del metodo
name	String	nombre metodo de pago
type	String	metodo
extra	Object
reference1*	String	Referencia única de la transacción proporcionada en el envio de la peticion para generar el recurso
reference2	String	Permite anexar información extra proporcionada por el cliente
reference3	String	Permite anexar información extra proporcionada por el cliente
commerceId	String	identificacion del comercio
createdAt	String	Fecha y hora de creacion de la transacción
signature	String	Firma generada para la notificacion del webhook
data	Object	Objeto con todos los datos
Transaction	String

200: OK "Notificación recibida exitosamente"

Request

{
    "data": {
        "Transaction": {
            "id": 38**,
            "amount": 20000,
            "cost": 500.0,
            "Status": {
                "id": 2,
                "description": "Transacción aprobada"
            },
            "Resource": {
                "id": 1002***,
                "key": 18,
                "PaymentMethod": {
                    "id": 133,
                    "name": "PSE"
                },
                "extra": {
                    "reference1": "435sdfsdf4",
                    "reference2": "reference2",
                    "reference3": "reference3",
                    "commerceId": "5641849815618"
                }
            },
            "createdAt": "2023-02-16 11:06:59",
            "updatedAt": "2023-02-16 11:08:54"
        }
    },
    "signature": "aa2f472ad7e84524a02d1716b56fc16ec2a87***"
}

500: Internal Server Error "Error inesperado"