Documentación de la API de PayCaddy

Cabe señalar que la responsabilidad de validar la exactitud y el formato de los datos introducidos recae en el cliente PayCaddy, lo que significa que nuestra API devolverá una respuesta correcta siempre que se cumplan los siguientes parámetros, independientemente de la exactitud de la información o de la duplicación de los datos compartidos:

1. Los campos FirstName y LastName deben sumar un total máximo de 22 caracteres que deben enviarse desinfectados, eliminando los caracteres especiales y limitándose al rango ASCII.
2. Ninguno de los campos debe enviarse como NULL.
3. El campo de correo electrónico debe seguir un formato de correo electrónico estándar.

Además de las verificaciones de formato, es importante destacar la responsabilidad del cliente de enviar sistemáticamente los campos restantes con la información correcta:

1. El campo "salary" debe incluir el salario mensual del usuario en USD.
2. El campo "pep" indica si la persona física para la que se crea el usuario está políticamente expuesta.

PEP: Persona a la que se ha confiado una responsabilidad pública destacada. Normalmente, una PEP presenta un mayor riesgo de implicación potencial en sobornos y corrupción en virtud de su posición e influencia.

El control sobre la duplicación de usuarios debe ser gestionado por el cliente PayCaddy. Nuestra API generará múltiples userIds distintos independientemente de si los datos compartidos son idénticos en las llamadas duplicadas.

Si este evento no genera errores, el sistema responderá con un mensaje HTTP 200 OK. La respuesta correcta replica los datos introducidos y añade información sobre los parámetros isActive y el walletId inicial asociado al userId, además de cargar un timestamp de la fecha de creación de dicho usuario.

Cabe señalar que la responsabilidad de validar la exactitud y el formato de los datos introducidos recae en el cliente PayCaddy, lo que significa que nuestra API devolverá una respuesta correcta siempre que se cumplan los siguientes parámetros, independientemente de la exactitud de la información o de la duplicación de los datos compartidos:

1. Los campos FirstName y LastName deben sumar un total máximo de 22 caracteres que deben enviarse desinfectados, eliminando los caracteres especiales y limitándose al rango ASCII.
2. Ninguno de los campos debe enviarse como NULL.
3. El campo de correo electrónico debe seguir un formato de correo electrónico estándar.

Además de las verificaciones de formato, es importante destacar la responsabilidad del cliente de enviar sistemáticamente los campos restantes con la información correcta:

1. El campo "RUC" debe incluir el número del Registro Único de Contribuyentes o su homólogo internacional para la identificación tributaria como VATIN, CUIT, CNPJ, NIT o RUT.
2. El campo "numOfRegistration"  debe incluir el número de registro de la persona jurídica determinado por la institución. Este campo puede replicar los datos de "RUC"  en caso de que la información no sea aplicable en su jurisdicción.
3. En el campo "kindOfBusiness"  se debe introducir una breve descripción de la actividad económica realizada por la persona jurídica. La API de NeoBank no valida la información detallada proporcionada en este campo; sin embargo, es crucial garantizar el envío de información precisa, ya que será utilizada por el equipo de cumplimiento para evaluar al usuario.

Si este evento no genera errores, el sistema responderá con un mensaje HTTP 200 OK. La respuesta correcta replica los datos introducidos y añade información sobre los parámetros isActive y el walletId inicial asociado al userId, además de cargar un timestamp de la fecha de creación de dicho usuario.

Cabe señalar que la responsabilidad de validar la exactitud y el formato de los datos introducidos recae en el cliente PayCaddy, lo que significa que nuestra API devolverá una respuesta correcta siempre que se cumplan los siguientes parámetros, independientemente de la exactitud de la información o de la duplicación de los datos compartidos:

1. Los campos FirstName y LastName deben sumar un total máximo de 22 caracteres que deben enviarse desinfectados, eliminando los caracteres especiales y limitándose al rango ASCII.
2. Ninguno de los campos debe enviarse como NULL.
3. El campo de correo electrónico debe seguir un formato de correo electrónico estándar.

Además de las verificaciones de formato, es importante destacar la responsabilidad del cliente de enviar sistemáticamente los campos restantes con la información correcta:

1. El campo "salary" debe incluir el salario mensual del usuario en USD.
2. El campo "pep" indica si la persona física para la que se crea el usuario está políticamente expuesta.

PEP: Persona a la que se ha confiado una responsabilidad pública destacada. Normalmente, una PEP presenta un mayor riesgo de implicación potencial en sobornos y corrupción en virtud de su posición e influencia.

El control sobre la duplicación de usuarios debe ser gestionado por el cliente PayCaddy. Nuestra API generará múltiples userIds distintos independientemente de si los datos compartidos son idénticos en las llamadas duplicadas.

Si este evento no genera errores, el sistema responderá con un mensaje HTTP 200 OK. La respuesta correcta replica los datos introducidos y añade información sobre los parámetros isActive y el walletId inicial asociado al userId, además de cargar un timestamp de la fecha de creación de dicho usuario.

Esta llamada debe realizarse asociándola a un userId activo previamente creado.

El campo de currency debe considerar los códigos de la norma ISO 4217. (Por ejemplo, los dólares estadounidenses se introducirían con el código "USD").

El campo description se emplea para dar un nombre a la wallet creada y describir su uso.

El campo "walletType" define si el wallet puede o no asociarse a una tarjeta de crédito (ver creditCard POST). Este booleano debe mantenerse como "0" para todos los wallets creados para tarjetas de débito, tarjetas prepago, o para la gestión de fondos y transferencias. Para los wallets creados para tarjetas de crédito de tipo prefunding, el "walletType" debe definirse como "1".

Esta llamada se encarga de realizar un pago para restablecer el crédito del wallet asociado al walletId pasado como parámetro.

Este método debe ser realizado periódicamente por el usuario, teniendo en cuenta las características establecidas en el momento de crear el wallet de crédito (ver UtcCreateLastPayment en CreditWallet).

El campo llamado 'amountToCapital'  determina la cantidad que el usuario está reportando, lo que tendrá un impacto en la cantidad disponible y la cantidad adeudada por el usuario dentro de la línea de crédito.

El campo ' currency ' corresponde a la moneda del monedero. El campo 'statement ' se utilizará para dejar una breve descripción de la operación realizada y, por último, el campo 'restoreCredit ' proporciona una funcionalidad booleana para restablecer la operatividad de las líneas de crédito bloqueadas.

El campo "amountToInterest " es opcional para mantener un registro de los intereses generados por la línea de crédito asociada a un walletId.

Si tiene éxito, se generará el informe de pago con los datos especificados, y la llamada devolverá un HTTP 200 detallando la fecha en la que se realizó el informe, así como los valores del límite de la tarjeta y el saldo disponible.

Si se produce un error en la llamada, la API de NeoBank responderá con un error HTTP 400. Los errores más comunes pueden incluir:

• WalletId inválido.
• El valor de la moneda no coincide con la moneda original del wallet.

El valor del atributo "status" puede ser:

True si el monedero está activado y disponible para transacciones.
False si está bloqueado, ya sea por el sistema o por impago (ver 'reportPayCredit').

La respuesta satisfactoria de esta llamada, además de la información proporcionada, incluye una marca de tiempo con la fecha de ejecución de la transacción y un identificador único de transacción que permite recuperar la información asociada con la llamada GET.

Si hay algún problema con los datos proporcionados, la API de PayCaddy responderá con un error HTTP 400.

Si hay algún problema con los datos proporcionados, la API de PayCaddy responderá con un error HTTP 400.

La API responderá con un error HTTP 400 si se trata de un transactionId incorrecto o de un transactionId que no está relacionado con un PayOut.

En esta llamada se debe especificar el walletId desde el que se envían los fondos y el walletId al   que se envían los fondos. El campo "currency"  debe cargar el código de la moneda asociada a ambos monederos siguiendo el estándar ISO 4217.

La API de PayCaddy no gestiona las conversiones de moneda, por lo que es necesario tener en cuenta que ambos monederos deben estar configurados bajo la misma moneda.

El importe introducido en el campo "amount"  debe estar en céntimos siguiendo el estándar de las demás llamadas a la API de PayCaddy.

El campo "statement" le permite introducir una descripción de la transacción para futuras consultas y visualización en el front-end.

La respuesta satisfactoria a esta llamada carga un identificador de transacción único y la marca de tiempo de su aceptación.

En caso de error en la llamada, la API de NeoBank responderá con un error HTTP 400 descriptivo.

Comúnmente, la llamada fallará si los walletIds involucrados en la transacción pertenecen a un userId inactivo, es decir, que mantiene su atributo "isActive" como "false".

Del mismo modo, la llamada siempre fallará si el walletIdFrom no mantiene el saldo adecuado para cubrir la transacción o cuando el código de moneda de ambos wallets no sea el mismo que el de la llamada Transfer POST.

La API responderá con un error HTTP 400 descriptivo si se proporciona un ID de transacción incorrecto o si el ID de transacción no está relacionado con una transferencia.

La estructura de los datos compartidos en cada transacción sigue el mismo formato que todas las notificaciones de transacciones. (Véase Webhooks de transacciones).

Cada transacción de tarjeta en la carga útil de la respuesta será una versión stringificada de los Webhooks de notificación de transacciones, aumentada con tres campos adicionales:

• c51MonedaImporteTransaccion: Representa la moneda utilizada para la transacción en el TPV.
• c6ImporteMonedaTransaccion: Denota el importe de la transacción en la moneda utilizada en el TPV.
• isSettled: Indica el estado de liquidación de una operación. Un valor de "false" significa que las transacciones están sin liquidar o en tránsito, mientras que "true" indica que las transacciones se han liquidado.

Dado que PayCaddy abstrae el proceso de liquidación para sus clientes, este campo es particularmente pertinente para casos de uso específicos como anulaciones y cancelaciones fuera de línea.

La lista de transacciones recuperada abarcará todas las transacciones con tipos de transacción "c1tipo" que afecten al saldo del monedero. No se incluirán "c1tipo" adicionales como las transacciones denegadas.

Las transacciones del proceso por lotes con valores de "c1tipo" de "transaccionCorregidaNegativa" y "transaccionCorregidaPositiva" se incorporarán a la lista recuperada, alineándose con la lógica esperada en los webhooks.

Cada transacción de monedero se presentará en su carga útil de respuesta 200 estándar:

Parámetros Explicación:

Petición:

• walletId: El identificador único del monedero, esencial para obtener las transacciones asociadas.
• startDate & toDate: Establezca el intervalo de fechas para la recuperación de transacciones. Para recuperar y paginar todas las transacciones, utilice la fecha actual para ambos campos.
• maxTransactions: Determina el máximo de transacciones a devolver. Si existen más transacciones dentro del intervalo de fechas, se excluirán.
• offset: Establece el punto de partida de las transacciones, obtenidas en orden cronológico inverso, lo que facilita la paginación.
• c43IdentificadorComercio: Un filtro opcional basado en un comerciante específico. Por ejemplo, "UBER" recupera todas las transacciones con "UBER" en su identificador de comercio.

Respuesta:

• transactionListJson: Contiene una cadena JSON de todas las transacciones solicitadas en orden cronológico inverso.
• totalItems: Especifica el total de transacciones en el transactionListJson.
• currentPage: Indica la página actual en función de totalItems y la solicitud de offset.
• totalPáginas: Muestra el total de páginas en función de totalItems y la solicitud de maxTransactions.

Paginación:

Para gestionar la paginación, ajuste la opción maxTransactions y offset en su solicitud. Esto garantiza una exploración controlada de las transacciones históricas, manteniendo un rendimiento UX/UI ágil.

En página actual y totalPáginas se incluyen en cada respuesta por conveniencia, ambos calculados a partir de la totalItems y offset parámetros.

Por ejemplo, con un totalItems de "25" y un offset de "125", el página actual sería "6", mostrando las transacciones numeradas del 126 al 150 del intervalo de fechas en orden cronológico inverso.

Una vez marcada la transacción, el estado y las actualizaciones de la devolución de cargo se notificarán a los clientes a través del webhook de ChargebackOperations. (Véase Webhooks)

La API responderá con un error HTTP 422 "tarjeta no encontrada" si el cardId proporcionado no coincide con el del cliente autenticado.

En caso de que el Límite sea 0 o no se haya establecido previamente, la respuesta llevará un mensaje de "No stablish internal limit" como atributo del límite.

‍

La API responderá con un error HTTP 422 "tarjeta no encontrada" si el cardId proporcionado no coincide con el del cliente autenticado.

Cada solicitud incluye el userId al que debe asociarse la tarjeta y el walletId cuyo saldo utilizará la tarjeta.

El campo physicalCard indica si se trata de una tarjeta que debe imprimirse físicamente (true) o, por el contrario, de una tarjeta exclusivamente digital (false).

Los datos de impresión de las tarjetas se extraen de los campos almacenados en la creación de usuarios, por lo que es importante tener en cuenta que las tarjetas se imprimen teniendo en cuenta los campos FirstName y LastName en el caso de personas físicas y el campo RegisteredName en el caso de personas jurídicas. Es fundamental garantizar la integridad de estos campos en el flujo de creación de usuarios, incluyendo la limitación de caracteres, ya que afecta al posterior flujo de creación de tarjetas.

El "code" enviado en la llamada debe ser proporcionado por el equipo de PayCaddy para cada tipo y variación de tarjeta incluida en el proyecto de habilitación. Es decir, para un proyecto que habilite la emisión de una tarjeta de débito virtual o física para personas físicas, se proporcionarían dos códigos diferentes, uno para usuario final físico y otro para usuario final virtual. Es responsabilidad del cliente invocar correctamente las llamadas teniendo en cuenta el tipo de usuario y la condición de impresión asociada al código proporcionado.

La respuesta satisfactoria de la llamada de creación de tarjeta de débito devuelve un mensaje 200 que lleva el identificador único de la tarjeta que debe utilizarse en todas las llamadas de operación de tarjeta (véase cardOperations). Además del cardId, la respuesta 200 también proporciona un booleano que indica si la tarjeta está operativa o no, y un campo de estado que describe el estado de la tarjeta.

A continuación se detallan los posibles estados:

PendingAck - Para tarjetas físicas recién creadas que no han sido activadas. (véase AckReception POST)

Temporarilyblocked - Para bloqueos autogestionables. (véase UnblockCard POST)

Cancel - Para tarjetas canceladas (ver CancelCard POST)

Active - Para tarjetas activas

Los datos sensibles de la tarjeta (PAN y CVV) pueden ser consultados mediante las llamadas checkPan POST y checkCvv POST. Sin embargo, es importante tener en cuenta que estos datos NO deben almacenarse en bases de datos, ya que implican requisitos de ciberseguridad asociados a la norma PCI que se han abstraído con el uso del cardId en la API de PayCaddy.

La fecha de caducidad de la tarjeta se presenta en la respuesta satisfactoria de la llamada de creación de tarjeta en el campo "dueDate" siguiendo el formato AAAAMM.

En caso de error o incoherencia con los datos proporcionados, la API responderá con un error 400 descriptivo de uno de los posibles motivos más comunes:

1. El userId al que se va a asociar la tarjeta no existe o está inactivo.
2. El walletId al que se va a asociar la tarjeta no existe o no pertenece al usuario introducido.
3. El código enviado en la llamada no coincide con el tipo de usuario al que debe asociarse la tarjeta.
4. El código proporcionado en la llamada no coincide con el tipo de tarjeta (virtual o física) que se intenta crear.

Cada solicitud incluye el userId al que debe asociarse la tarjeta y el walletId cuyo saldo utilizará la tarjeta.

El campo physicalCard indica si se trata de una tarjeta que debe imprimirse físicamente (true) o, por el contrario, de una tarjeta exclusivamente digital (false).

Los datos de impresión de las tarjetas se extraen de los campos almacenados en la creación de usuarios, por lo que es importante tener en cuenta que las tarjetas se imprimen teniendo en cuenta los campos FirstName y LastName en el caso de personas físicas y el campo RegisteredName en el caso de personas jurídicas. Es fundamental garantizar la integridad de estos campos en el flujo de creación de usuarios, incluyendo la limitación de caracteres, ya que afecta al posterior flujo de creación de tarjetas.

El "code" enviado en la llamada debe ser proporcionado por el equipo de PayCaddy para cada tipo y variación de tarjeta incluida en el proyecto de habilitación. Es decir, para un proyecto que habilite la emisión de una tarjeta de débito virtual o física para personas físicas, se proporcionarían dos códigos diferentes, uno para usuario final físico y otro para usuario final virtual. Es responsabilidad del cliente invocar correctamente las llamadas teniendo en cuenta el tipo de usuario y la condición de impresión asociada al código proporcionado.

La respuesta satisfactoria de la llamada de creación de tarjeta de débito devuelve un mensaje 200 que lleva el identificador único de la tarjeta que debe utilizarse en todas las llamadas de operación de tarjeta (véase cardOperations). Además del cardId, la respuesta 200 también proporciona un booleano que indica si la tarjeta está operativa o no, y un campo de estado que describe el estado de la tarjeta.

A continuación se detallan los posibles estados:

PendingAck - Para tarjetas físicas recién creadas que no han sido activadas. (véase AckReception POST)

Temporarilyblocked - Para bloqueos autogestionables. (véase UnblockCard POST)

Cancel - Para tarjetas canceladas (ver CancelCard POST)

Active - Para tarjetas activas

Los datos sensibles de la tarjeta (PAN y CVV) pueden ser consultados mediante las llamadas checkPan POST y checkCvv POST. Sin embargo, es importante tener en cuenta que estos datos NO deben almacenarse en bases de datos, ya que implican requisitos de ciberseguridad asociados a la norma PCI que se han abstraído con el uso del cardId en la API de PayCaddy.

La fecha de caducidad de la tarjeta se presenta en la respuesta satisfactoria de la llamada de creación de tarjeta en el campo "dueDate" siguiendo el formato AAAAMM.

En caso de error o incoherencia con los datos proporcionados, la API responderá con un error 400 descriptivo de uno de los posibles motivos más comunes:

1. El userId al que se va a asociar la tarjeta no existe o está inactivo.
2. El walletId al que se va a asociar la tarjeta no existe o no pertenece al usuario introducido.
3. El código enviado en la llamada no coincide con el tipo de usuario al que debe asociarse la tarjeta.
4. El código proporcionado en la llamada no coincide con el tipo de tarjeta (virtual o física) que se intenta crear.

En cada llamada se incluye el userId al que se debe asociar la tarjeta y el walletId con cuyo saldo se realizará la transacción.

Para las tarjetas de crédito, el walletId a asociar debe ser un monedero de crédito (véase WalletCredits) o un monedero de prepago con el atributo "walletType" igual a "1".

El campo tarjetafísica indica si se trata de una tarjeta que debe imprimirse físicamente true o, por el contrario, de una tarjeta exclusivamente digital false.

Los datos de impresión de las tarjetas se extraen de los campos almacenados en la creación de usuarios, por lo que es importante asegurarse de que las tarjetas se imprimen teniendo en cuenta los campos FirstName y LastName en el caso de personas físicas y RegisteredName en el caso de personas jurídicas. Es fundamental garantizar la integridad de estos campos en el flujo de creación de usuarios, incluyendo las limitaciones de caracteres, ya que esto afecta al posterior flujo de creación de tarjetas.

El code enviado en la llamada debe ser proporcionado por el equipo de PayCaddy para cada tipo y variación de tarjeta incluida en el proyecto de habilitación, es decir, para un proyecto que habilite la emisión de una tarjeta de crédito virtual o física para personas físicas, se proporcionarían dos códigos diferentes, uno para la física del usuario final y otro para la virtual. Es responsabilidad del cliente invocar correctamente las llamadas teniendo en cuenta el tipo de usuario y la condición de impresión asociada al código proporcionado.

La respuesta satisfactoria de la llamada de creación de tarjeta de débito devuelve un mensaje 200 que lleva el identificador único de la tarjeta que debe utilizarse en todas las llamadas de operación de tarjeta (véase cardOperations). Además del cardId, la respuesta 200 también proporciona un booleano que indica si la tarjeta está operativa o no, y un campo de estado que describe el estado de la tarjeta.

A continuación se detallan los posibles estados:

PendingAck - Para tarjetas físicas recién creadas que no han sido activadas. (véase AckReception POST)

Temporarilyblocked - Para bloqueos autogestionables. (véase UnblockCard POST)

Cancel - Para tarjetas canceladas (ver CancelCard POST)

Active - Para tarjetas activas

Los datos sensibles de la tarjeta (PAN y CVV) pueden ser consultados mediante las llamadas checkPan POST y checkCvv POST. Sin embargo, es importante tener en cuenta que estos datos NO deben almacenarse en bases de datos, ya que implican requisitos de ciberseguridad asociados a la norma PCI que se han abstraído con el uso del cardId en la API de PayCaddy.

La fecha de caducidad de la tarjeta se presenta en la respuesta satisfactoria de la llamada de creación de tarjeta en el campo "dueDate" siguiendo el formato AAAAMM.

En caso de error o incoherencia con los datos proporcionados, la API responderá con un error 400 descriptivo de uno de los posibles motivos más comunes:

1. El userId al que se va a asociar la tarjeta no existe o está inactivo.
2. El walletId al que se va a asociar la tarjeta no existe o no pertenece al usuario introducido.
3. El código enviado en la llamada no coincide con el tipo de usuario al que debe asociarse la tarjeta.
4. El código proporcionado en la llamada no coincide con el tipo de tarjeta (virtual o física) que se intenta crear.

‍

Esta llamada es especialmente necesaria para gestionar el estado de actividad de la tarjeta, ya que la respuesta satisfactoria también incluye la actividad booleana "isActive" y el campo descriptivo "status" , además de los otros campos de la respuesta satisfactoria de creación de tarjeta.En caso de que se envíe un cardId no válido, la API de PayCaddy responderá con un error HTTP 400.

Si se produce un error HTTP 500, comunique la incidencia al equipo de asistencia de PayCaddy.

Una vez al día, a una hora límite específica, todas las tarjetas físicas creadas en el ciclo se envían a la imprenta. La llamada ackReception POST no devolverá una respuesta satisfactoria hasta que la tarjeta solicitada se haya impreso, por lo que es una llamada que sólo debe realizarse cuando se disponga de la tarjeta impresa o 48 horas después de una respuesta satisfactoria para la creación de tarjetas.

El objetivo de esta llamada es permitir la entrega de la tarjeta al titular en estado inactivo, a la espera de la validación de la recepción por parte del titular una vez tenga la tarjeta en sus manos.

La validación tarjeta en mano debe gestionarse comparando los datos introducidos por el titular de la tarjeta (como un rango del PAN o del CVV) con los resultados de las llamadas realizadas para obtener dichos datos sensibles (véase checkPan POST y checkCvv POST). Si los datos introducidos coinciden, se puede realizar la llamada ackReception POST para activar la tarjeta por primera vez, simplemente enviando en la llamada el cardId de la tarjeta a activar.

La respuesta satisfactoria a la llamada simplemente replica el cardId introducido. En caso de encontrar un error 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

A menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

A menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

La API podría responder con un error HTTP 400 descriptivo si se trata de un intento de bloquear una tarjeta que ya ha sido bloqueada previamente. Para las tarjetas activas, a menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

La API podría responder con un error HTTP 400 descriptivo si se trata de un intento de desbloquear una tarjeta activa. En el caso de tarjetas bloqueadas previamente que estén inactivas, a menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

A menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

A menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

La API responderá con un error HTTP 400 descriptivo si se envía un PIN que no sigue el formato de 4 dígitos numéricos, de lo contrario, a menos que se introduzca un cardId incorrecto, la API responderá con un mensaje HTTP 200 correcto.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

La API de PayCaddy podría responder con un error HTTP 400 descriptivo si se intenta cancelar una tarjeta que ya ha sido cancelada.

En caso de encontrar un error HTTP 500, póngase en contacto con el equipo de soporte de PayCaddy con los detalles del caso.

El propósito de esta llamada es específicamente para asignar una URL de recepción de webhooks y una contraseña de seguridad que garantice que las notificaciones recibidas en la dirección asignada son legítimas y genuinas.

Durante la integración, una vez realizada correctamente la llamada NotificationEnlist POST, se debe gestionar una prueba con el equipo de integración de PayCaddy para verificar la recepción correcta de las cargas útiles de la transacción.

Principales tipos de transacciones

Hay tres tipos principales de transacciones que recibirá como tipo en línea:

1. PeticiónAutorización: Esta transacción disminuirá el saldo del cliente.
2. AutorizaciónComunicación: Esta transacción también disminuirá el saldo del cliente.
3. ComunicaciónAnulación: Esta transacción aumentará los fondos disponibles en el monedero del cliente.
4. ReversalRequest: Este tipo de transacción declara una solicitud de anulación de dinero que se procesará fuera de línea a través del Proceso por Lotes. Esta transacción tendrá un importe declarado de "0". Una vez que la red confirme la devolución, el importe procesado se declarará en la "TransaccionCorregidaPositiva" relacionada a través del Proceso por Lotes.

El tipo de transacción se indica en el campo "c1Tipo" del webhook. Por ejemplo, si el campo "c1Tipo"  indica que se trata de una transacción de tipo "PeticiónAutorización", deberá presentarse como una deducción en el saldo disponible.

Tipos adicionales de notificación de transacciones

Hay 9 tipos adicionales de transacciones que recibirá en línea a través de la URL alistada. Debe tenerse en cuenta que estos tipos no afectan al saldo y son meramente informativos del uso de la tarjeta y describen la causa de las transacciones rechazadas.

Estos tipos se verán como valores en el campo "c1Tipo" de la notificación webhook:

1. DENEGADA: La transacción fue rechazada por una razón no especificada.
2. DENEGADA. PIN INCORRECTO: La transacción ha sido rechazada porque el PIN introducido es incorrecto.
3. DENEGADA. INTENTOS PIN EXCEDIDO: La transacción ha sido rechazada porque se ha superado el número máximo de intentos de introducción del PIN.
4. DENEGADA. TARJETA NO EFECTIVA: La transacción ha sido rechazada porque la tarjeta no es válida o no está activa.
5. DENEGADA. CVV2 INCORRECTO: La transacción ha sido rechazada porque se ha introducido un CVV2 incorrecto.
6. IMPORTE SUPERA LÍMITE: La transacción ha sido rechazada porque el importe de la transacción supera el límite permitido para la tarjeta.
7. NO HAY FONDOS: La transacción ha sido rechazada porque la cuenta asociada a la tarjeta no tiene fondos suficientes.
8. EXCEDIDO NUMERO DE OPERACION DIARIO: La transacción ha sido rechazada porque se ha superado el número máximo de operaciones diarias permitidas para la tarjeta.
9. FECHA CADUCIDAD ERRONEA: La transacción ha sido rechazada porque se ha introducido una fecha de caducidad incorrecta.
10. NotificacionDenegacion: Estas no se verán normalmente en los webhooks recibidos, sino que se encontrarán al utilizar el endpoint TransactionDetailList. Representan una transacción que ha sido rechazada debido a fondos insuficientes.

En el esquema del JSON enviado en la mayoría de estos tipos adicionales de notificaciones, los campos "c38NumeroAutorizacion" y "c11NumeroIdentificativoTransaccion" están presentes para comodidad del cliente, sin embargo, es importante mencionar que estos campos no siempre contendrán información y, por lo tanto, se presentarán como cadenas vacías ("").

Transacciones MoneySend

Para mantenerse informado sobre los detalles de una transacción MoneySend iniciada, PayCaddy proporciona notificaciones webhook. Estos webhooks siguen la misma estructura y viajan a través de la misma URL que otras notificaciones de transacciones. Sin embargo, las transacciones MoneySend pueden ser identificadas por el valor c3CodigoProceso de "820000".

Cuando maneje notificaciones webhook de MoneySend, almacénelas como cualquier otra notificación de transacción. La principal diferencia radica en cómo se procesa la transacción.

Las transacciones MoneySend con c1Tipo igual a "PeticionAutorizacion " deben ser tratadas como transacciones positivas añadiendo fondos al saldo del monedero del destinatario en lugar de deducir fondos.

Las transacciones MoneySend con c1Tipo igual a "ComunicacionAnulacion " deben ser tratadas como transacciones negativas restando fondos del saldo del monedero del destinatario en lugar de deducir fondos.

Al registrar las transacciones con tarjeta o monedero en el front-end, esto debería reflejarse mostrando el importe de dichas transacciones como entradas a los fondos del monedero en lugar de cargos.

Aviso de actualización: A partir del 11 de abril, la funcionalidad de nuestro Proceso por lotes se ha ampliado para incluir la notificación webhook "TransaccionConfirmada". Esta incorporación garantiza una supervisión exhaustiva de todas las liquidaciones de transacciones, tanto si coinciden con los importes autorizados inicialmente como si requieren ajustes.

Para gestionar la finalización del ciclo de vida de una transacción, utilizamos un proceso por lotes para actualizar y finalizar el ciclo de vida de cada transacción aprobada, lo que permite una rápida visibilidad de los datos de liquidación reales en su programa de emisión de tarjetas.

PayCaddy aprovecha este procesamiento por lotes para enviar notificaciones a través de la ruta webhook transaccional convencional (véase NotificationEnlist POST) como parte de un proceso diario para confirmar y/o ajustar el importe previamente aprobado para cada transacción.

Nuestro sistema utiliza tres tipos clave de notificaciones webhook para gestionar diversos resultados de transacciones:

1. TransaccionCorregidaPositiva
   • Se emite cuando la liquidación final da lugar a un ajuste positivo del importe inicialmente autorizado, con lo que se añaden fondos al monedero del usuario.
2. TransaccionCorregidaNegativa
   • Se emite cuando la liquidación final da lugar a un ajuste negativo, por lo que se deducen fondos del monedero del usuario.
3. TransaccionConfirmada (Nuevo)
   • Se introduce para confirmar que la transacción se ha liquidado exactamente por el importe autorizado inicialmente, proporcionando una confirmación clara y precisa del resultado de la transacción.

Un par de ejemplos de transacciones que podrían corregirse mediante un proceso por lotes son:

1. Alquiler de coches: Cuando un cliente alquila un coche, la empresa de alquiler suele autorizar un importe inicial en la tarjeta del cliente para cubrir el coste del alquiler y los posibles daños. Sin embargo, el importe final puede variar en función del uso real del vehículo y de otros factores, como la distancia recorrida o el coste del combustible. En estos casos, podría utilizarse el mensaje corrector "TransaccionCorregidaPositiva" o "TransaccionCorregidaNegativa" para ajustar el importe final cargado en la tarjeta del cliente, una vez devuelto el vehículo y realizado el cálculo final.
2. Reservas de hotel: Cuando un cliente reserva una habitación de hotel, el hotel suele bloquear una cantidad en la tarjeta del cliente para cubrir el coste de la estancia y posibles cargos adicionales, como el minibar o el servicio de habitaciones. Al final de la estancia, el importe final puede ser diferente del bloqueado inicialmente, en función del uso real de estos servicios adicionales. En estos casos, podría utilizarse el mensaje corrector "TransaccionCorregidaPositiva" o "TransaccionCorregidaNegativa" para ajustar el importe final cargado en la tarjeta del cliente, una vez calculados los cargos finales.

El procesamiento por lotes agiliza la gestión de las transacciones diferidas y garantiza una liquidación adecuada, reduciendo las discrepancias y la necesidad de conciliación manual. Estos webhooks mejoran la gestión de las transacciones, minimizan los errores y optimizan la gestión global.

Siempre que sea posible, se recomienda cotejar la transacción corregida con la transacción original. De este modo, los titulares de las tarjetas comprenderán mejor cómo y por qué se ha modificado su saldo.

Esta práctica mejora la transparencia y fomenta la confianza de los clientes al permitirles estar al tanto de todas las transacciones y cambios realizados en sus cuentas. Es esencial que los titulares de tarjetas se sientan informados y en control de su actividad financiera.

Como parte de nuestro flujo KYC integrado para personas físicas, después de que los usuarios completen los pasos de verificación de identidad en la URL compartida en el campo kycURL (véase POST de usuario final), el sistema de nuestro proveedor de verificación de identidad procesa los datos enviados y los compara con listas negras y realiza comprobaciones AML. Nuestra API aprovecha estas verificaciones y proporciona notificaciones de estado a través de webhook.

Para recibir correctamente las notificaciones de las verificaciones de KYC, es necesario mantener una URL para recibir mensajes de la API de PayCaddy a través de webhook. Debes ponerte en contacto con el equipo de integración de PayCaddy para configurar el envío de notificaciones a esa URL.

‍

Webhooks de verificación KYC

El webhook de validación KYC (Know Your Customer) es una notificación enviada a los clientes con información relevante sobre el estado del proceso de verificación KYC. La información se entrega en formato JSON y puede incluir diferentes estados y descripciones, en función de los casos de verificación.

Campos:

• metadata: información crucial para identificar al usuario en forma de su userId.
• status: el estado de la verificación KYC, que puede ser "verified", "rejected" o "reviewNeeded".
• description: descripción detallada del estado de la verificación.
• fullName: nombre completo del usuario.
• age: edad del usuario.
• timeStamp: la marca de tiempo ISO 8601 de la respuesta del webhook.

Estados de verificación y descripciones

El flujo del webhook para una validación sigue el diagrama descrito a continuación.

Rejected: Este estado hace referencia a cuando un usuario no ha superado el proceso de verificación KYC. A continuación se detallan los diferentes casos de rechazo.

ReviewNeeded: Este estado hace referencia a cuando un usuario no ha superado el proceso de verificación KYC. A continuación se detallan los diferentes casos de rechazo.