🪝 Webhooks, Estados y Callbacks

Las transacciones de Koywe siguen un camino (principalmente) lineal: se crean, se pagan y se entregan. Todo esto se notifica a través de webhooks (ver más abajo) o se devuelve cuando llamas a nuestras APIs para hacer seguimiento a una orden.

Los posibles estados de una orden son:

• WAITING: La orden ha sido creada y está esperando a ser pagada.

• PENDING: La orden ha sido pagada y está en cola para su ejecución.

• EXECUTING: La orden está siendo ejecutada. es decir: La transacción se está enviando a la blockchain o al banco.

• IN_PROGRESS: Los fondos, ya sean criptos o fiat, están en camino a su destino.

• INVALID_WITHDRAWALS_DETAILS: Solo válido para las rampas de salida. Los datos bancarios eran incorrectos y el banco de destino ha rechazado la transferencia.

• REJECTED: La orden ha sido rechazada por el usuario o el procesador de pagos.

• DELIVERED: Los fondos, ya sean criptos o fiat, han sido entregados con éxito.

​

Webhook de Eventos

Para facilitar la integración, tenemos la posibilidad de alertarte cuando pasa algo o de definir formas de validar ciertas cosas contigo antes de ejecutar las transacciones.

Puedes configurar una URL para recibir solicitudes cada vez que se activa un evento para una transacción. Los posibles eventos son:

payment_created: se crea la orden, Koywe espera el pago en fiat o en cripto. El estado de la orden será WAITING.

payment_received: se paga la orden. Koywe confirma el pago con éxito y entregará amountOut. El estado de la orden será PENDING.

payment_rejected: se rechaza la orden. Algo sucedió y se rechazó la orden. Este evento NO se envía para las transferencias bancarias y normalmente se debe a un error o cancelación por parte del usuario. El estado de la orden será REJECTED.

wire_order_canceled: se cancela la orden. Una orden pendiente existente ha sido cancelada automáticamente debido a la creación de una nueva orden de transferencia. El estado de la orden será REJECTED.

payment_rejected_by_compliance: se rechaza la orden. Algo sucedió con el análisis de compliance o riesgo y se rechazó la orden. Este evento NO se envía para las transferencias bancarias y normalmente se debe a un problema con la información del usuario. El estado de la orden será REJECTED.

payment_expired: la orden ha expirado. Solo se envía para las transferencias bancarias. El usuario tardó demasiado en transferir o Koywe no pudo detectar el pago a tiempo. Se debería crear otra orden o cotización para asegurar un precio. El estado de la orden será REJECTED.

payment_received_modified_order_amount: Este evento de webhook se activa cuando se modifica una orden debido a un depósito bancario recibido. Este evento por ahora solo se aplica a las transferencias bancarias realizadas en Perú. Cuando un usuario realiza un depósito bancario, puede ocurrir que el monto depositado sea mayor o menor al monto original de la orden. En este caso, la orden se ajusta automáticamente al monto recibido. Para modificar la orden, se genera un nuevo presupuesto ( quote ) basado en el monto recibido y se actualiza la orden con este nuevo presupuesto. De esta manera, la orden reflejará el monto correcto después del depósito bancario. Este evento también envia un objeto en donde se recibirá la orden original( originalOrder ) y la orden recalculada ( orderAdjustedByBankIncome )

Eventos específicos de onramp (“currency-crypto”):

crypto_tx_sent: se envía la transacción criptográfica después de que se confirma el pago en fiat. El estado de la orden será IN_PROGRESS.

crypto_delivered: la transacción criptográfica es confirmada por la cadena de bloques. El estado de la orden será DELIVERED.

crypto_tx_failed: la transacción criptográfica falló. Esto no debería suceder, pero ocurre en algunos casos mínimos (1 de cada 10 mil). Si llegara a suceder, intentaríamos la transacción nuevamente y volverías a recibir los eventos de más arriba. El estado de la orden será REJECTED.

Eventos específicos de offramp (“crypto-currency”):

fiat_sent: se envía la transferencia en fiat desde la cuenta de Koywe. El estado de la orden será IN_PROGRESS.

fiat_delivered: el fiat se entrega, según el banco de Koywe. El estado de la orden será DELIVERED.

invalid_withdrawals_details: se intentó la transferencia en fiat, pero el banco rechazó la transacción porque la cuenta o el dueño de la cuenta no coincidían con los registros existentes. Hay un endpoint especial para corregir los datos de la transacción, puedes revisarlo en los docs de la API. El estado de la orden será INVALID_WITHDRAWALS_DETAILS.

Adicionalmente, podrás definir un secret para validar que somos nosotros quienes estamos enviando esos requests. Usando ese secret, encriptamos los parámetros enviados y agregamos el hash para que puedas verificar el mensaje:

const signature \= crypto.createHmac('sha256',
secret).update(JSON.stringify(payload)).digest('hex')

Ejemplo de evento reportado:

{
  "eventName": "crypto_delivered", // Evento de la lista anterior
  "orderId": "5a3288ea-0bd4-44d2-af11-aae1f88bbd61", // Id de la orden, ver arriba
  "orderType": "currency-crypto", // Este atributo especifica el tipo de orden, que puede ser OnRamp ("currency-crypto") o OffRamp ("crypto-currency").
  "externalId": "34ae1f88bbd6", // Este atributo se devuelve solo si el 'externalId' se especificó durante el proceso de creación de la orden.
  "timeStamp": "2022-10-26T22:36:41.658Z",
  "signature": "ed40d34ab7a587cf1a16338a16cc7765ae4420936677482bb33f5f738e4f7189" // hash
}

​

Webhooks KYC

Si estás usando nuestro proceso de KYC, también podrás recibir notifications por webhook cuando un usuario comienza o completa una verificación. Por ahora, estos eventos llegarán a la misma url de los webhooks de operaciones.

verification_started: El usuario hace clic en el botón para comenzar la verificación de identidad. El estado KYC del usuario cambiará de notVerified a processing.

verification_inputs_completed: El usuario ha terminado de cargar la información y enviar los formularios, así que comenzamos a procesar todos los datos. El estado KYC del usuario permanecerá en processing.

verification_completed: Hemos terminado de analizar los datos del usuario y tenemos un resultado. El estado KYC del usuario cambiará a verified o reviewNeeded. Para este último, nuestro equipo de cumplimiento debe completar una revisión manual para llevar al usuario a verified o rejected.

verification_expired: El usuario no ha terminado dentro de los 30 minutos después de iniciar el proceso. El estado KYC volverá a notVerified.

Example of a request:

{
  "eventName": "verification_started", // evento, de la lista más arriba
  "orderId": "KYC_EVENT",
  "timeStamp": "2022-10-26T22:36:41.658Z",
  "data": "guillermo@koywe.com",
  "signature": "ed40d34ab7a587cf1a16338a16cc7765ae4420936677482bb33f5f738e4f7189" // hash
}

​

Callback de Autenticación

Podrás definir una URL en tu API que nos confirme que un usuario puede operar en tu contexto de cliente. De esta forma, cada vez que un usuario quiera comprar, vender, o revisar información privada, revisaremos contigo antes de dejarlo actuar.

Nuestra plataforma asume que devolverás algo que se parezca a un booleano positivo y soporta varios métodos de autenticación.

// usuario compra cripto
const createOrder (payload) {
    if (!validUser(payload.email)) throw new Error('user not allowed');
    else continue
}
// validamos contra tu API antes de dejarlo seguir
const validUser(email) {
    const payload = { email }
    const headers = { 'Authorization': 'Bearer superJWT' }
    const { data } = await axios.post(urlExternalAPI, payload, { headers })
    reurn data
}

​

Webhooks Actualización número de documento

Si realizaste un cambio de número de documento, nosotros realizaremos una validación asíncrona de los datos de la persona. Los resultados de esa valdación serán enviados a través de webhook

UPDATE_DOCUMENT_NUMBER: Luego de una validación de datos, se recibirá un evento con este nombre en donde habrá un mensaje de confirmación, o un mensaje de error ya que hubo discrepancia en los datos del usuario.

• document_number_sucessfully_updated: El proceso de validación de datos finalizo con éxito y el número de document se actualizo correctamente.

• document_number_failed_to_update: Hubo un error en el proceso de validación de datos, por ejemplo: “Account does not have any personal info”, “Account not found”, “There is incompatible personal info between the account and metamap”.

Ejemplo de una request:

{
"eventName": "document_number_sucessfully_updated", // O "document_number_failed_to_update" si falló,
"orderId": "UPDATE_DOCUMENT_NUMBER",
"timeStamp": "2022-10-26T22:36:41.658Z",
"data": {
"email": {{email}},
"message": {{Mensaje de error o completado}},
"details": "The date of birth in the account ({date}) doesn't match the one in metamap ({date}). || Name mismatch detected. Expected: {name}. Found: {name}"
},
"signature": "ed40d34ab7a587cf1a16338a16cc7765ae4420936677482bb33f5f738e4f7189" // hash
}

​

Webhooks Depósitos

Este evento avisará a los clientes si llega un depósito a nuestro sistema de un usuario que no tiene ordenes vigentes

NEW_DEPOSIT_REGISTERED: Al procesar el depósito recibido, y asociarlo a un usuario, si este no tiene órdenes vigentes quedará en su balance, en este momento se disparará este evento

• deposit_without_order

Ejemplo de una request:

{
  "eventName": "deposit_without_order",
  "orderId": "NEW_DEPOSIT_REGISTERED",
  "timeStamp": "2024-06-07T16:17:54.258Z",
  "data": {
    "documentNumber": "{{documentNumber}}",
    "currency": "ARS",
    "clientId": "65c4ed085f193b99de04f061",
    "accountBalanceAmount": 50000,
    "email": "{{email}}"
  },
  "signature": "ae0e02ae78ef00c5b2c623d3abf41c2785434af0bbba55e2371b1fa38c6b63f3"
}