WebHook · PaymentsWay Docs

Recibe notificaciones en tiempo real sobre el resultado de cada transacción. PaymentsWay hace un HTTP POST a tu endpoint cuando una transacción cambia de estado.

Tu endpoint debe usar HTTPS (SSL). Las peticiones sin SSL serán rechazadas. Tu página de notificación no debe incluir código HTML — actualiza tus bases de datos y responde con el status correcto.

Estados y cómo responder

Responde con 200 únicamente cuando el estado es Exitosa (id 34). Para todos los demás estados responde 201.

ID	Estado	Tu respuesta HTTP
`1`	Creada	`201`
`34`	Exitosa	`200`
`35`	Pendiente	`201`
`36`	Fallida	`201`
`38`	Cancelada	`201`
`39`	Reembolsada	`201`
`40`	Pendiente efectivo	`201`

Campos del payload

Campo	Tipo	Descripción	Método
`id`	number	Identificador interno único de la transacción en PaymentsWay.	Todos
`amount`	number	Valor cobrado al cliente.	Todos
`externalorder`	string	Referencia de la orden generada por tu sistema.	Todos
`fullname`	string	Nombre completo del cliente.	Todos
`ip`	string	Dirección IP del cliente durante la transacción.	Todos
`additionaldata`	JSON	Información adicional enviada al crear la transacción.	Todos
`idstatus`	object	Estado de la transacción: `{ id, nombre }`.	Todos
`idperson`	object	Datos del cliente: `{ id, firstname, lastname, identification, email, phone }`.	Todos
`paymentmethod`	object	Método de pago usado: `{ id, nombre }`.	Todos
`idmerchant`	string	ID del comercio receptor del pago.	Todos
`innerexception`	object	Detalle del rechazo PSE: `{ codigo, causal }`. Solo cuando el estado es NOT_AUTHORIZED en PSE.	PSE

Ejemplo de payload — Transacción exitosa

JSON

{
  "id"            : "822",
  "ammount"       : 4000,
  "externalorder" : "12001",
  "ip"            : "172.0.0.1",
  "fullname"      : "",
  "additionaldata": null,
  "idstatus"      : { "id": 34, "nombre": "Exitosa" },
  "idperson"      : {
    "id"            : "60",
    "firstname"     : "Ejemplo nombre",
    "lastname"      : "Ejemplo apellido",
    "identification": "1200345601",
    "email"         : "",
    "phone"         : ""
  },
  "paymentmethod": { "id": 2, "nombre": "PSE" },
  "idmerchant"   : "1"
}

Ejemplo de payload — PSE rechazado (con innerexception)

Solo cuando el estado PSE es NOT_AUTHORIZED, el campo innerexception indica la causal detallada del rechazo bancario.

JSON

{
  "id"            : "id",
  "amount"        : 100,
  "externalorder": "external",
  "ip"            : "127.0.0.1",
  "fullname"      : "",
  "additionaldata": {},
  "innerexception": { "codigo": "00001", "causal": "CUENTA NO EXISTE" },
  "idstatus"      : { "id": 36, "nombre": "Fallida" },
  "idperson"      : {
    "id": "", "firstname": "", "lastname": "",
    "identification": "", "email": "", "phone": ""
  },
  "paymentmethod": { "id": 2, "nombre": "PSE" },
  "idmerchant"   : ""
}

Ejemplo de handler en Node.js

JavaScript — Node.js / Express

app.post('/webhook/paymentsway', async (req, res) => {
  const { id, externalorder, idstatus, idperson, amount } = req.body;

  if (idstatus?.id === 34) {
    // Transacción exitosa — actualiza tu base de datos
    await db.updateOrder(externalorder, { status: 'paid', amount });
    return res.status(200).send('OK');
  }

  // Cualquier otro estado
  return res.status(201).send('RECEIVED');
});

Estados y cómo responderCopiar enlace

Campos del payloadCopiar enlace

Ejemplo de payload — Transacción exitosaCopiar enlace

Ejemplo de payload — PSE rechazado (con innerexception)Copiar enlace