Documentación de la API de PayCaddy

Integre emisión de tarjetas fácilmente en sus aplicaciones y sistemas.

Introducción

Bienvenido a la documentación del API de Paycaddy, una plataforma integral y flexible diseñada para permitir a las empresas y desarrolladores integrar fácilmente servicios bancarios y financieros en sus aplicaciones y sistemas.

Nuestra API está construida como una interfaz REST. El principal beneficio es que acepta form-encoded request bodies y devuelve respuestas JSON-encoded, usando códigos estándar de respuesta HTTP lo cual debería hacer nuestra API familiar para cualquier persona con experiencia previa utilizando APIs.

A partir de ese momento y utilizando esta documentación como guía, debes ser capaz de integrarte y probar llamados para:

  • Crear usuarios de tipo persona natural y jurídica. (ver USERS)
  • Crear wallets para cada usuario que crees. Esta opción sera útil si vas a integrar tarjetas de tipo credito pre fondeado o si quieres manejar mas de un wallet por usuario. (ver WALLETS)
  • Gestionar balances de wallets creados por medio de PayIns, PayOuts y transferencias entre wallets. (ver WALLET OPERATIONS)
  • Crear tarjetas vinculadas a los wallets creados. (ver CARDS)
  • Gestionar tarjetas creadas. (ver CARD OPERATIONS)
Importante destacar que la creación de tarjeta cuenta con endpoints distintos para tarjetas de débito, crédito y prepago. En la exploración inicial, nuestro equipo comercial debe haberles asignado los detalles específicos de los perfiles de su programa de tarjetas, lo que definirá a cuál o cuales endpoints deberán hacer llamados para la creación de sus tarjetas y también un código único para su perfil asignado que deben incluir los llamados de creación de tarjeta.

Acceso y autenticación en Sandbox

Para empezar un proceso de integración, debes inicialmente solicitar API Keys de integración en la sección de Desarrolladores de nuestra página web. Los API keys van a ser entregados vía email al responsable técnico.

El manejo de las llaves es un tema de gran importancia y es responsabilidad del destinatario de las llaves mantenerlas seguras. Las llaves secretas no deberán ser compartidas en ningún sitio accesible al público como GitHub, código client-side, etc.

La autenticación al API deberá ser efectuada via X-API Key. Es necesario proveer el API Key como el valor básico de usuario, sin necesidad de proveer password.

Todas las llamadas deben realizarse a través de HTTPS; cualquier llamada realizada a través de HTTP o sin autenticación fallará.

Con las credenciales de integración podrás hacer llamados al ambiente de pruebas de NeoBank API de forma directa. Nuestro equipo proveerá herramientas para hacer pruebas sobre los endpoints mientras vas desarrollando tu código hacia nuestros ambientes (Puede elegir entre Swagger o Postman).

Estructura de entidades

El NeoBank API cuenta con 3 entidades fundamentales con las que se interactuará cada vez que se consuma algún endpoint para completar los distintos flujos disponibles. Dichas entidades identifican a los usuarios finales del servicio de emisión de tarjetas, los monederos o contenedores virtuales de dinero y las tarjetas asociadas a ellos.

Un diagrama de las entidades principales de PayCaddy y sus relaciones entre sí

UserID:
Identifica de forma única a un EndUser o MerchantUser indistintamente. El UserID es la entidad primaria del NeoBank API. El flujo de creación de un EndUser o MerchantUser siempre dan por resultado la creación de un userID y a su ves un walletID asociado.

W‍alletID:
El walletId es el identificador del contenedor de dinero electrónico al cual se acreditan y debitan fondos por medio de PayIns, PayOuts y/o transacciones de la o las tarjetas asociadas al mismo. Un userId siempre estará asociado a mínimamente un walletId, sin embargo puede contener múltiples walletIds si así requiere la solución del cliente.

CardID:
Son los identificadores únicos de la tarjeta que además sirven como una abstracción del PAN de las tarjetas emitidas, evitando la necesidad del almacenamiento de información sensitiva de las tarjetas. 

Resumen de flujos

Los flujos disponibles con el uso del NeoBank API se categorizan en base a la entidad principal que registran, modifican o consultan. A un alto nivel los flujos se correlacionan de la siguiente manera:

Flujo de uso del punto final de Paycaddy. Utilice nuestros servicios en este orden y con esta arquitectura en mente

Flujo de usuarios

La creación de nuevos userIds en el NeoBank API sigue dos flujos separados dependiendo del tipo de persona a ser ingresada al sistema. 

EndUser es como se denominan los usuarios creados para personas naturales.
MerchantUser es como se denominan los usuarios creados para personas jurídicas.

Importante destacar que la creación de usuarios endpoints distintos para EndUsers y MerchantUsers.

En la exploración inicial, nuestro equipo comercial debe haberles asignado los detalles específicos de los perfiles de su programa de tarjetas, lo que definirá a cuál o cuales endpoints deberán hacer llamados para la creación de sus usuarios y también las obligaciones de KYC pertinentes.
Flujo de verificación para los diferentes tipos de usuario que puedes crear en la API de PayCaddy

Flujo de tarjetas

La API de NeoBank dispone de llamadas diferenciadas para la creación de tarjetas de débito, crédito y prepago. A través de estas llamadas, es posible crear una tarjeta física o virtual para un UserID existente vinculada al saldo disponible en un WalletID específico de ese usuario.

Todas las tarjetas se crean utilizando un código de parametrización único para cada producto de tarjeta, que debe ser previamente solicitado al equipo de integración de PayCaddy.

La creación de una tarjeta se inicia con la llamada DebitCard POST , CreditCard POST o PrepaidCard POST, dependiendo del servicio de emisión adquirido.

Es importante tener en cuenta el tipo de usuario para el que se ha parametrizado la tarjeta. Las tarjetas parametrizadas para personas físicas sólo pueden crearse asociándolas a UserIDs que representen EndUsers, mientras que las parametrizadas para personas jurídicas sólo pueden crearse asociándolas a MerchantUsers.

Una vez que se le haya concedido un código de creación de tarjetas, podrá empezar a probar la creación de tarjetas en el entorno de pruebas.

Flujo general para la creación y activación de una tarjeta en la API de PayCaddy.

Flujo de crédito

Para los programas de emisión de tarjetas de crédito que utilizan líneas de crédito, se utilizarán los endpoints descritos a continuación para gestionar los fondos disponibles en los wallets asociados a cada línea de crédito.

Si las tarjetas son de crédito prepago, consulte mas detalles en la descripción del endpoint Wallet POST para crear wallets que tengan la capacidad de crear tarjetas de crédito.

La operación de crédito sigue el siguiente flujo y utiliza los endpoints detallados en esta sección.

Flujo de creación de carteras de crédito.

EndUser - Persona física

EndUser POST

URL de la solicitud: https://api.paycaddy.dev/v1/endUsers

La creación de un nuevo usuario para una persona física comienza con una llamada POST en la que se consume un endpoint para enviar la información básica del usuario:

{
 "email": "string",
 "firstName": "string",
 "lastName": "string",
 "occupation": "string",
 "placeofwork": "string",
 "pep": "bool",
 "salary": "integer",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 }
}

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": false,
 "walletId": "string",
 "kycUrl": "string",
 "creationDate": "2022-07-13T21:07:21.166Z"
}

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.

Si se produce un error, el sistema responderá con uno de los siguientes mensajes de error con código de estado 400:

{
 "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "traceId": "00-68857a5c83b83b498f4c49d8a61d91cb-1a140dcbf259a24d-00",
 "errors": {
   "FirstName": [
     "The FirstName field is required."
   ]
 }
}

{
"type": "",
"title": "The value provided for the name exceeds the maximum value",
"status": 0,
"detail": "",
"instance": ""
}

{
 "type": "",
 "title": "Invalid format for email",
 "status": 0,
 "detail": "",
 "instance": ""
}

En caso de que te encuentres con un mensaje de error 500, esto podría indicar un error interno del servidor en el sistema. Si te enfrentas a esta situación, te pedimos que informes al equipo de PayCaddy para que podamos investigar y resolver el problema de manera eficiente.

Una vez asignados los identificadores de usuario y wallet, el usuario final deberá completar la verificación KYC para completar el procedimiento de creación del perfil. Hasta que se complete esta verificación, el campo de control "isActive" permanecerá asignado como falso, inhabilitando cualquier procedimiento.

En la respuesta de creación de usuario(EndUser POST), se presenta un enlace a la validación de identidad asociada al userId en Metamap, donde se presentarán al usuario final las instrucciones y pasos a seguir para completar la verificación.

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": false,
 "walletId": "string",
 "kycUrl": "https%3a%2f%2fsignup.getmati.com%2f%3fmerchantToken%
3d6046cc2a54816f001bedd641%26flowId%3d6046cc2a54816f0
01bedd640%26metadata%3d%7b%22userid%22%3a%226955ea0f4
f3-4254-b10a-0181f307298c%22%7d",

 "creationDate": "2022-07-12T15:29:01.8271862+00:00"
}

Es importante tener en cuenta que la kycURL se comparte aplicando una codificación URL que permite el envío de metadatos (userId) que vinculan la validación con el usuario creado. Para asegurar la activación del usuario al completar con éxito la validación, es necesario asegurar que la URL a la que se redirige al usuario desde la interfaz front-end carga la siguiente estructura:

https://signup.getmati.com/?merchantToken=6046cc2a54816f001dedd641&
flowId=6046cc2a54816f001bedd640&
metadata={"userid":"a955ea0f-34f3-4254-b10a-0181f30729kd"}

Para obtener información completa sobre KYC, consulte el capítulo KYC de esta documentación.

EndUser GET

URL de la solicitud: https://api.paycaddy.dev/v1/endUsers/

La llamada GET para un usuario final permite conocer los datos almacenados de un userId concreto, especialmente el walletId de su monedero inicial y el estado de actividad de este usuario en el campo "isActive". Ambos datos son cruciales para las demás llamadas a la API de NeoBank.

Esta llamada puede utilizarse para verificar el estado del usuario en cualquier punto del flujo.

https://api.paycaddy.dev/v1/endUsers/5bcf7be1-717c-49ed-a8a4-0170892308ab

//Response - 200
{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "kycUrl": "string",
 "creationDate": "2023-03-22T19:13:46.178Z"
}

MerchantUser - Persona jurídica

MerchantUser POST

URL de la solicitud: https://api.paycaddy.dev/v1/merchantUsers

La creación de un nuevo usuario para una persona jurídica comienza con una llamada POST en la que se consume un endpoint para el envío de los datos básicos de la persona jurídica.

{
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 }
}

{
 "id": "string",
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "creationDate": "2022-07-18T22:29:45.914Z"
}

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.

Los controles de duplicación de usuarios deben ser gestionados por su equipo de desarrollo. Nuestra API generará varios userIds distintos, independientemente de si los datos compartidos son idénticos en las llamadas duplicadas.

Si se produce un error, el sistema responderá con uno de los siguientes mensajes de error con código de estado 400:

{
 "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "traceId": "00-68857a5c83b83b498f4c49d8a61d91cb-1a140dcbf259a24d-00",
 "errors": {
   "FirstName": [
     "The FirstName field is required."
   ]
 }
}

{
"type": "",
"title": "The value provided for the name exceeds the maximum value",
"status": 0,
"detail": "",
"instance": ""
}

{
 "type": "",
 "title": "Invalid format for email",
 "status": 0,
 "detail": "",
 "instance": ""
}

En caso de que te encuentres con un mensaje de error 500, esto podría indicar un error interno del servidor en el sistema. Si te enfrentas a esta situación, te pedimos que informes al equipo de PayCaddy para que podamos investigar y resolver el problema de manera eficiente.

MerchantUser GET

URL de la solicitud: https://api.paycaddy.dev/v1/merchantUsers/

La llamada GET para un merchantUser permite conocer los datos almacenados de un userId concreto, especialmente el walletId de su wallet inicial y el estado de actividad de este usuario en el campo "isActive". Ambos datos son cruciales para las demás llamadas a la API de NeoBank.

Esta llamada puede utilizarse para verificar el estado del usuario en cualquier punto del flujo.

https://api.paycaddy.dev/v1/merchantUsers/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "id": "string",
 "email": "string",
 "registeredName": "string",
 "numOfRegistration": "string",
 "ruc": "string",
 "kindOfBusiness": "string",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "creationDate": "2022-07-18T22:29:45.914Z"
}

EndUserSR - Flujo KYC delegado

EndUserSR POST

URL de solicitud: https://api.paycaddy.dev/v1/SR/endUserSRs/

La creación de un nuevo usuario para una persona física con un flujo KYC delegado comienza con una llamada POST en la que se consume un endpoint para el envío de los datos básicos del usuario:

{
 "email": "string",
 "firstName": "string",
 "lastName": "string",
 "occupation": "string",
 "placeofwork": "string",
 "pep": "bool",
 "salary": "integer",
 "telephone": "string",
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
   "homeNumber": "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string",
}
"idUrlFront": "string",
"idUrlBack": "string",
"residenceProofUrl": "string",
}

{
 "id": "string",
 "firstName": "string",
 "lastName": "string",
 "email": "string",
 "telephone": "string",
 "placeOfWork": "string",
 "pep": true,
 "salary": 0,
 "address": {
   "addressLine1": "string",
   "addressLine2": "string",
"homeNumber" : "string",
   "city": "string",
   "region": "string",
   "postalCode": "string",
   "country": "string"
 },
 "isActive": true,
 "walletId": "string",
 "idUrlFront": "string",
"idUrlBack": "string",
"residenceProofUrl": "string",
 "creationDate": "2022-07-13T21:07:21.166Z"
}

Los campos "idUrlFront", "idUrlBack" y "residenceProofUrl" deben enviarse con URL únicas donde se almacenan imágenes del anverso y reverso del documento nacional de identidad del usuario y una prueba de residencia. Los parámetros específicos para subir estos documentos deben haber sido acordados previamente con el departamento de cumplimiento de PayCaddy.

Los usuarios creados bajo este flujo nacen con un estado activo pero están sujetos a bloqueos en caso de que la información KYC enviada en la llamada de creación sea rechazada por el equipo de cumplimiento 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.

Wallets

Wallet POST

URL de la solicitud: https://api.paycaddy.dev/v1/wallets

La creación de un wallet se realiza a través de una llamada POST que lleva la siguiente estructura:

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "walletType": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "balance": 0,
 "amountWithheld": 0,
 "creationDate": "2022-07-19T20:08:29.970Z"
}

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".

Las "Main Wallets"  creadas automáticamente en el flujo de creación de usuarios mantienen un "walletType " de "0".

En caso de que se produzca un error en la llamada, la API de NeoBank responderá con un error HTTP 400 con la descripción del error.

En caso de encontrar un error HTTP 500, por favor contacte con el equipo de soporte de PayCaddy con la descripción de la incidencia.

Wallet GET

URL de la solicitud: https://api.paycaddy.dev/v1/wallets/

https://api.paycaddy.dev/v1/wallets/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "balance": 0,
 "amountWithheld": 0,
 "creationDate": "2022-07-19T20:08:29.970Z"
}

La llamada GET para monederos permite recuperar la información asociada al walletId consultado. Esta llamada es particularmente importante para comprobar el saldo disponible en un wallet y el saldo retenido debido a transacciones pendientes.

El saldo total se refleja en el campo "balance" de la respuesta 200 correcta a esta llamada, mientras que el saldo retenido se refleja en el campo "amountWithheld".

Todas las cantidades se reflejan en céntimos, lo que significa que 1.000,00 USD se representarían como 100000.

La llamada puede fallar si se proporciona un walletId incorrecto, en cuyo caso la API NeoBank respondería con un error HTTP 400.

{
 "type": "",
 "title": "Wallet 'c4d165d1-721d-4d78-a48d-017f0c6facf8' not found",
 "status": 0,
 "detail": "",
 "instance": ""
}

WalletsPerUserId POST

URL de la solicitud: https://api.paycaddy.dev/v1/WalletsPerUserIds

Este endpoint permite obtener una lista de todos los wallets asociados a un ID de usuario.
Realizando una petición POST con el ID del usuario, el sistema devuelve una lista con los identificadores de los diferentes wallets que tiene el usuario.

{
 "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{  
"walletsJson": "[
{\"Id\":\"216fa217-6826-48b8-ab5b-0180891cef30\",\"BDateUtcCreate\":\"2022-05-03T08:50:16.4959966\",\"BTimestamp\":\"AAAAAAAb6Pk=\",
\"ClientId\":\"1c5a29f5-b018-40c7-a6d4-017efe423d42\",\"UserId\":\"qa2c3b2a-23f6-49be-b882-0180891cef30\",\"Currency\":\"USD\",\"Description\":\"Main wallet\",\"AmountAvailable\":38574,\"AmountWithheld\":1110756}
,
{\"Id\":\"d6928675-a4fe-4752-8e7e-018099d30fe1\",\"BDateUtcCreate\":\"2022-05-06T14:43:07.7804616\",\"BTimestamp\":\"AAAAAAAbv6Q=\",
\"ClientId\":\"1c5a29f5-b018-40c7-a6d4-017efe423d42\",\"UserId\":\"ea2c3b2a-23f6-49be-b882-0180891cef30\",\"Currency\":\"USD\",\"Description\":
\"SecondaryWallet\",\"AmountAvailable\":381599,
\"AmountWithheld\":29253372}

]"}

La respuesta a esta llamada trae toda la información de las múltiples wallets asociadas al mismo UserId en un formato de string que mantiene la misma estructura que la respuesta de la llamada Wallet GET.

Wallets de crédito

Wallet Credit POST

URL de la solicitud: https://api.paycaddy.dev/v1/walletCredits/

La creación de un wallet de crédito se realiza a través de la llamada POST que lleva la siguiente estructura:

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "time": 0,
 "limit": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "limit": 0,
 "creationDate": "2023-01-17T10:11:42.287Z"
}

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

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

El campo "description"  se utiliza para dar nombre al wallet según su uso previsto, pero no es obligatorio para crear un nuevo wallet.

El campo "time"  define el número de días que la línea de crédito debe permanecer activa. Este campo se utiliza para definir el plazo de un crédito renovable (véase ReportPayCredit).

Por último, el campo  "limit"  establece el importe en céntimos del límite de crédito que tendrá el wallet.

Wallet Credit GET

URL de la solicitud: https://api.paycaddy.dev/v1/walletCredits/

La creación de un wallet de crédito se realiza a través de la llamada POST que lleva la siguiente estructura:

{
 "userId": "string",
 "currency": "string",
 "description": "string",
 "time": 0,
 "limit": 0
}

{
 "id": "string",
 "userId": "string",
 "currency": "string",
 "description": "string",
 "limit": 0,
 "creationDate": "2023-01-17T10:11:42.287Z"
}

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

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

El campo "description"  se utiliza para dar nombre al wallet según su uso previsto, pero no es obligatorio para crear un nuevo wallet.

El campo "time"  define el número de días que la línea de crédito debe permanecer activa. Este campo se utiliza para definir el plazo de un crédito renovable (véase ReportPayCredit).

Por último, el campo  "limit"  establece el importe en céntimos del límite de crédito que tendrá el wallet.

Credit Operations

ReportPayCredit POST

URL de la solicitud: https://api.paycaddy.dev/v1/reportPayCredits

Para restablecer las líneas de crédito rotativo se utiliza el endpoint ReportPayCredit. Los usuarios que tienen un crédito activo deben realizar los pagos correspondientes para restablecer el crédito.

La llamada para reportar pagos se realiza utilizando la siguiente estructura:

{
 "walletId": GUID,
 "amountToCapital": 0,
 "amountInterest": 0,
 "currency": "string",
 "statement": "string",
 "restoreCredit": true
}

{
 "creationDate": "2023-01-16T16:22:39.975Z",
 "limit": "string",
 "amountAvailable": "string"
}

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.

ChangeWalletLimit POST

URL de la solicitud: https://api.paycaddy.dev/v1/walletCredits/changeWalletLimit

Este método se utilizará para modificar los límites previamente establecidos en los wallets de crédito de los usuarios de la API de PayCaddy. Los límites pueden variar para aumentar o disminuir el límite, dependiendo del motivo de ejecución del método.

{
 "walletId": "string",
 "newLimit": 0,
 "currency": "string",
 "statement": "string"
}

{
 "walletId": "string",
 "newLimit": 0
}

La llamada se asociará al 'walletId' proporcionado, seguido del valor introducido en el campo 'newLimit' , que representará el importe que debe actualizarse en la propiedad 'limit'  del monedero.

El campo  'currency'  debe corresponder a la propiedad 'currency'  del monedero indicado, y finalmente, el campo 'statement' proporciona una breve descripción de la operación realizada.

Todos los importes se reflejan en céntimos, lo que significa que 1.000,00 USD se representaría como 100000.

La llamada puede fallar si se proporciona un walletId incorrecto, en cuyo caso la API de PayCaddy respondería con un error HTTP 400.

CheckCreditOperation GET

URL de la solicitud: https://api.paycaddy.dev/v1/CheckCredit

La llamada GET de CheckCreditOperation permite recuperar información sobre un ' walletId' consultado. Esta llamada es especialmente importante para comprobar el estado de actividad del monedero.

Si tiene éxito, la llamada devolverá un HTTP 200 detallando el 'walletId' asociado y el estado del monedero."

https://api.paycaddy.dev/v1/CheckCredit/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "walletId": "string",
 "status": "string"
}

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').

Wallet Operations

PayIn POST

Url de solicitud: https://api.paycaddy.dev/v1/payIns

‍PayIn es el método de la API de PayCaddy para añadir fondos a un monedero específico. Es una llamada sencilla que carga la información del 'walletId' al que se van a cargar los fondos, la cantidad a ingresar en el monedero en céntimos, el código de la moneda según ISO 4217, y una descripción de la transacción.

{
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-20T20:47:04.060Z"
}

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.

{
 "type": "Decoding body",
 "title": "Error ",
 "status": 422,
 "detail": "Wallet not found",
 "instance": ""
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

PayIn GET

URL de solicitud: https://api.paycaddy.dev/v1/payIns/

La llamada GET para un PayIn permite acceder a la información relacionada con un transactionId específico. La respuesta satisfactoria de esta llamada carga la siguiente estructura:

https://api.paycaddy.dev/v1/payIns/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-20T20:47:04.056Z"
   }
 ]
}

La llamada puede fallar si se proporciona un walletId incorrecto, en cuyo caso la API de PayCaddy respondería con un error HTTP 400.

PayOut POST

URL de la solicitud: https://api.paycaddy.dev/v1/payOuts

PayOut es un método para debitar fondos disponibles en un wallet específico. A diferencia de una transferencia, el uso de este método elimina la existencia de los fondos de la API de NeoBank. Este método debe asociarse a una operación contable que requiera dicha llamada.

De forma similar a PayIn, la respuesta satisfactoria devolverá los datos introducidos acompañados de un identificador único de transacción y su marca de tiempo.

{
 "walletIdFrom": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdFrom": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-20T20:47:04.060Z"
}

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

{
 "type": "Decoding body",
 "title": "Error ",
 "status": 422,
 "detail": "Wallet not found",
 "instance": ""
}

La API responderá con el mismo error que si no se encontrara el wallet si el walletId está asociado a un usuario bloqueado.

Se recomienda verificar el estado del usuario asociado al walletId al que se van a abonar los fondos antes de realizar la llamada PayOut POST.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

{
 "type": "",
 "title": "Wallet does not have sufficient funds",
 "status": 0,
 "detail": "",
 "instance": ""
}

PayOut GET

URL de la solicitud: https://api.paycaddy.dev/v1/payOuts/

La llamada GET para un PayOut permite acceder a la información relacionada con un transactionId específico. La respuesta satisfactoria de esta llamada carga la siguiente estructura:

https://api.paycaddy.dev/v1/payOuts/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-20T20:47:04.056Z"
   }
 ]
}

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.

Transferir POST

URL de la solicitud: https://api.paycaddy.dev/v1/transfers

Para realizar transacciones dentro del entorno API de NeoBank entre dos monederos previamente creados, se debe utilizar la llamada Transfer POST, que tiene la siguiente estructura:

{
 "walletIdFrom": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string"
}

{
 "id": "string",
 "walletIdFrom": "string",
 "walletIdTo": "string",
 "amount": 0,
 "currency": "string",
 "statement": "string",
 "creationDate": "2022-07-22T15:54:08.059Z"
}

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.

Transferencia GET

URL de la solicitud: https://api.paycaddy.dev/v1/transfers/

La llamada GET para una transferencia entre monederos permite acceder a la información relacionada con un transactionId específico y lleva la siguiente estructura:

https://api.paycaddy.dev/v1/transfers/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "walletIdFrom": "string",
     "walletIdTo": "string",
     "amount": 0,
     "currency": "string",
     "statement": "string",
     "creationDate": "2022-07-22T16:07:33.092Z"
   }
 ]
}

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.

TransactionDetailList POST

URL de la solicitud: https://api.paycaddy.dev/v1/TransactionDetailList

Esta llamada POST recupera todas las transacciones de un cardId concreto proporcionado.

{
 "cardId": "904ee16a-db84-4120-9714-0180892341b3",
 "startDate": "2023-01-23T18:21:02.157Z"
}

{
 "transactionListJson": "[{\"c1Tipo\":\"PeticionAutorizacion\",\"c2CardId\":\"904ee16a-db84-4120-9714-0180892341b3\",\"c3CodigoProceso\":\"000000\",\"c4ImporteTrans
accion\":\"116\",\"c7FechaHoraTransaccion\":\"20230203194512\"
,\"c11NumeroIdentificativoTransaccion\":\"000088058\",\"c18Cod
igoActividadEstablecimiento\":\"4111\",\"c19CodigoPaisAdquiren
te\":\"724\",\"c38NumeroAutorizacion\":\"169\",\"c41TerminalId
\":\"00004001\",\"c42Comercio\":\"000000047219191\",\"c43Ident
ificadorComercio\":\"TRANVIA DE MURCIA        CHURRA-MURCIA  
         \"},{\"c1Tipo\":\"PeticionAutorizacion\",\"c2CardId\":\"904ee16a-db84-4120-9714-0180892341b3\",\"c3CodigoProceso\":\"000000\",\"c4ImporteTrans
accion\":\"2266\",\"c7FechaHoraTransaccion\":\"20230317135513\
",\"c11NumeroIdentificativoTransaccion\":\"000099870\",\"c18Co
digoActividadEstablecimiento\":\"5813\",\"c19CodigoPaisAdquire
nte\":\"724\",\"c38NumeroAutorizacion\":\"171\",\"c41TerminalI
d\":\"90315259\",\"c42Comercio\":\"000000175240563\",\"c43Iden
tificadorComercio\":\"BULEVAR CAFE EL RANERO   MURCIA
                  \"}]"
}

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).

TransactionDetailListByWallet POST

URL de la solicitud: https://api.paycaddy.dev/v1/TransactionDetailListByWallet

El punto final TransactionDetailListByWallet ofrece una vista detallada de todas las transacciones vinculadas a un monedero específico. Esto incluye transacciones específicas del monedero, como ingresos, pagos y transferencias, así como transacciones con tarjeta vinculadas al ID del monedero especificado.

{
 "walletId": "Your Wallet ID",
 "startDate": "Start Date in ISO Format",
 "toDate": "End Date in ISO Format",
 "maxTransactions": "Maximum Number of Transactions",
 "offset": "Number of Transactions to Skip",
 "c43IdentificadorComercio": "Optional Merchant Identifier Filter"
}

{
 "transactionListJson": "[{transaction1},{transaction2},...,{transactionN}]",
 "totalItems": "Total number of transactions within the requested date range",
 "currentPage": "Current page number indicator",
 "totalPages": "Total number of pages available"
}

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:

{
"c1Tipo": "string",
"c2CardId": "string",
"c3CodigoProceso": "string",
"c4ImporteTransaccion": "string",
"c7FechaHoraTransaccion": "string", // in yyyyMMddHHmmss format
"c11NumeroIdentificativoTransaccion": "string",
"c18CodigoActividadEstablecimiento": "string",
"c19CodigoPaisAdquirente": "string",
"c38NumeroAutorizacion": "string",
"c41TerminalId": "string",
"c42Comercio": "string",
"c43IdentificadorComercio": "string",
"c51MonedaImporteTransaccion": "string",
"c6ImporteMonedaTransaccion": "string",
"isSettled": "true"

}

  • 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.

ChargebackOperación POST

URL de la solicitud: https://api.paycaddy.dev/v1/ChargeBackOperation

Este endpoint permite marcar una transacción específica asociada a una tarjeta para que sea estudiada por un equipo de especialistas en devoluciones de cargo. Al solicitar el análisis de una devolución de cargo, el equipo evaluará si la transacción puede ser anulada y los fondos devueltos al titular de la tarjeta.

{
 "numeroidentificativoTransaction": "string",
 "cardId": "string"
}

{
 "TransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "IsChargeBack": true,
 "ChargeBackStatus": "string"
}

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)

Cambiar el Límite Interno de Cartera POST

URL de la solicitud: https://api.paycaddy.dev/v1/ChangeLimitIWL

Cada tarjeta generada por la API de PayCaddy tiene una serie de propiedades que se utilizan a la hora de realizar las transacciones. Una de ellas es el límite asignado por los clientes para controlar el gasto de sus usuarios. El valor del límite determinará la cantidad que se puede transaccionar y puede variar para cada usuario. Sólo los clientes pueden realizar cambios y actualizaciones en el valor del límite.

Los límites se restablecen al principio de cada mes, y cada transacción se aprueba de acuerdo con el límite vigente en ese momento.

{
   "cardId": "string",
   "limit": 0
}

{
   "cardId": "string",
   "limit": 0
}

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

Límite interno de la cartera GET

URL de la solicitud: https://api.paycaddy.dev/v1/ChangeLimitIWL

Para recuperar el límite actual de una tarjeta concreta debe utilizarse el método GET para el Límite interno de la cartera.

La solicitud debe realizarse con el cardId concreto que se desea consultar. En el siguiente ejemplo, el cardId aparece resaltado en la URL de la solicitud.

https://api.paycaddy.dev/v1/ChangeLimitIWL/3fa85f64-5717-4562-b3fc-2c963f66afa6

{
   "cardId": "string",
   "limit": 0
}

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.

Tarjetas de débito

DebitCard POST

URL de la solicitud: https://api.paycaddy.dev/v1/debitCards

Esta llamada permite la creación de una tarjeta de débito y sigue la siguiente estructura:

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

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.
Es importante tener en cuenta que los reintentos en caso de error deben gestionarse de forma responsable, es decir, creando plazos de al menos 5 segundos antes del reintento y limitando el número de reintentos a 3.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

DebitCard GET

URL de la solicitud: https://api.paycaddy.dev/v1/debitCards/

La llamada GET para tarjetas de débito permite consultar los datos de una tarjeta basándose en un cardId.

https://api.paycaddy.dev/v1/debitCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "userId": "string",
     "walletId": "string",
     "physicalCard": true,
     "code": "string",
     "isActive": true,
     "status": "string",
     "creationDate": "2022-08-01T21:57:16.932Z",
     "dueDate": 0
   }
 ]
}

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.

Tarjetas prepago

PrepaidCard POST

Request URL: https://api.paycaddy.dev/v1/prepaidCards

Esta es la llamada utilizada para crear Tarjetas Prepago asociadas a un userId y walletId concretos, y lleva la siguiente estructura:

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

{
 "type": "",
 "title": "Wallet does not have sufficient funds",
 "status": 0,
 "detail": "",
 "instance": ""
}

Es importante tener en cuenta que los reintentos en caso de error deben gestionarse de forma responsable, es decir, creando plazos de al menos 5 segundos antes del reintento y limitando el número de reintentos a 3.

PrepaidCard GET

URL de la solicitud: https://api.paycaddy.dev/v1/prepaidCards/

La llamada GET para tarjetas prepago permite consultar los datos de una tarjeta basándose en un cardId.

https://api.paycaddy.dev/v1/prepaidCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
 "data": [
   {
     "id": "string",
     "userId": "string",
     "walletId": "string",
     "physicalCard": true,
     "code": "string",
     "isActive": true,
     "status": "string",
     "creationDate": "2022-08-01T21:57:16.932Z",
     "dueDate": 0
   }
 ]
}

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.


Tarjetas de crédito

CreditCard POST

URL de la solicitud: https://api.paycaddy.dev/v1/CreditCards

Esta llamada permite la creación de una Tarjeta de Crédito asociada a un userId y walletId determinados. Se debe mantener la siguiente estructura para enviar los datos relevantes.

{
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string"
}

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": true,
 "status": "string",
 "creationDate": "2023-01-16T11:36:20.453Z",
 "dueDate": 0
}

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.

Es importante tener en cuenta que los reintentos en caso de error deben gestionarse de forma responsable, es decir, creando plazos de al menos 5 segundos antes del reintento y limitando el número de reintentos a 3.

CreditCard GET

URL de la solicitud: https://api.paycaddy.dev/v1/CreditCards/

La llamada GET para una tarjeta de crédito permite recuperar información relevante asociada a un cardId concreto proporcionado a través de la siguiente estructura:

https://api.paycaddy.dev/v1/CreditCards/5bcf7be1-717c-49ed-a8a4-0170892308ab

{
   "data": [
       {
           "id": "string",
           "userId": "string",
           "walletId": "string",
           "physicalCard": true,
           "code": "string"
           "isActive": true,
           "status": "string",
           "creationDate": "2022-08-01T21:57:16.932Z",
           "dueDate": 0
       }
   ]
}

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.

Card Operations

AckReception POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/ackReception

Como medida de seguridad en el proceso logístico de entrega de plásticos físicos, por defecto, todas las tarjetas físicas creadas en la API de NeoBank nacen inactivas. Esto se refleja en los campos "isActive" y "status" de las respuestas exitosas para la creación de estas tarjetas, así como al realizar una llamada GET para todos los tipos de tarjetas, como se ve en el siguiente ejemplo:

{
 "id": "string",
 "userId": "string",
 "walletId": "string",
 "physicalCard": true,
 "code": "string",
 "isActive": false,
 "status": "pendingAck",

 "creationDate": "2022-08-01T19:37:50.392Z",
 "dueDate": 0
}

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.

{
 "cardId": "string"
}

{
 "cardId": "string"
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckPAN POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/checkPan

Esta llamada permite acceder a datos sensibles como el número de tarjeta y la fecha de caducidad.
Las respuestas a esta llamada no deben almacenarse en bases de datos por motivos de seguridad.
Requiere un cardId como entrada y lleva la siguiente estructura:

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pan": "string",
 "expDate": 0
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckCVV POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/checkCvv

Esta llamada permite acceder a datos sensibles como el CVV (Card Verification Value) de la tarjeta.
Las respuestas a esta llamada no deben almacenarse en bases de datos por motivos de seguridad.
Requiere un cardId como entrada y lleva la siguiente estructura:

{
 "cardId": "string"
}

{
 "cardId": "string",
 "cvv": "string"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

BlockCard POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/blockCard

Esta llamada permite el cambio autogestionado del estado de actividad de la tarjeta. Esta llamada afecta directamente al booleano "isActive" transformándolo a "false" basándose en una simple llamada que sólo lleva el cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "false"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

UnblockCard POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/unblockCard

Esta llamada permite el cambio autogestionado del estado de actividad de la tarjeta. Esta llamada afecta directamente al booleano "isActive " transformándolo a "false" basándose en una simple llamada que sólo lleva el cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "true"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CheckPIN POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/checkPin

Esta llamada permite acceder a los datos confidenciales del PIN de la tarjeta, necesarios para todas las retiradas en cajeros automáticos y para las transacciones en puntos de venta de algunas regiones geográficas.

Las respuestas de esta llamada no deben almacenarse en bases de datos por motivos de seguridad.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

UnblockPIN POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/unblockPin

Esta llamada permite la reactivación del PIN de una tarjeta después de que se produzca un bloqueo de seguridad debido a tres intentos incorrectos. El número total de intentos incorrectos aceptables antes del bloqueo de seguridad es un parámetro que puede discutirse durante la fase de definición del alcance del proyecto, específicamente para perfiles de tarjeta personalizados.

Las respuestas de esta llamada no deben almacenarse en bases de datos por razones de seguridad.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

ChangePIN POST

URL de la solicitud: https://api.paycaddy.dev/v1/cardOperations/changePin

Esta llamada permite gestionar los datos sensibles del PIN de la tarjeta, que es necesario para todas las retiradas en cajeros automáticos y para algunas zonas geográficas en dispositivos de punto de venta. La llamada está diseñada para asignar un PIN de 4 dígitos especificado por el usuario. Las respuestas de esta llamada no deben almacenarse en bases de datos por razones de seguridad.

Las respuestas de esta llamada no deben almacenarse en bases de datos por razones de seguridad.

{
 "cardId": "string",
 "pin": "string"
}

{
 "cardId": "string",
 "pin": "string"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

CancelCard POST

URL de la petición: https://api.paycaddy.dev/v1/cardOperations/cancelCard

Esta llamada permite cancelar permanentemente una tarjeta previamente creada. Esta llamada afecta directamente al booleano "isActive ", cambiándolo a "false", así como al campo "status " cambiándolo a "Cancel"  desde una llamada que simplemente carga el cardId.

{
 "cardId": "string"
}

{
 "cardId": "string",
 "isActive": "false"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Webhooks

NotificationEnlist POST

URL de solicitud: https://api.paycaddy.dev/v1/NotificationEnlist

Las transacciones generadas en la red Mastercard por tarjetas creadas en la API NeoBank se detallan en notificaciones vía webhook que deben ser almacenadas en una base de datos para ser consumidas en un módulo de gestión de transacciones.

Estas notificaciones se envían a una URL dedicada y compartida con el equipo de PayCaddy de forma segura mediante el consumo del endpoint POST NotificationsEnlist. A continuación se detalla la estructura de la llamada empleada para alistar una URL para recibir Notificaciones de Transacciones:

{
 "URL": "string",
 "Password": "string"
}

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.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Notificaciones de transacciones

‍Cadavez que una tarjeta emitida en la API de NeoBank realice una transacción en la red Mastercard, se enviará a la URL alistada una carga útil como uno de los cuatro tipos de transacciones que se ejemplifican a continuación.

{
 "password": "password",
 "c1Tipo": "PeticionAutorizacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "ComunicacionAutorizacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "ComunicacionAnulacion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "PeticionDevolucion",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

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.

Es importante tener en cuenta que los webhooks de Notificación de Transacción se envían con atributos y valores nombrados en español.
Esta documentación traduce algunos términos para facilitar su comprensión.
El campo "c7FechaHoraTransaccion" representa la información de la hora de la transacción en la zona horaria en la que se adquirió la transacción en el formato "AAAAMMDDhhmmss".

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 ("").

{
 "password": password,
 "c1Tipo": "DENEGADA. INCORRECTO CVV2",
 "c2CardId": cardId,
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

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".

{
"password": "password",
"c1Tipo": "PeticionAutorizacion",
"c2CardId": "cardId",
"c3CodigoProceso": "820000",
"c4ImporteTransaccion": "000000001617",
"c7FechaHoraTransaccion": "20220429052901",
"c11NumeroIdentificativoTransaccion": "000004339",
"c18CodigoActividadEstablecimiento": "5999",
"c19CodigoPaisAdquirente": "442",
"c38NumeroAutorizacion": "040031",
"c41TerminalId": "00227759",
"c42Comercio": "227759000156182",
"c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

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.

Procesamiento Batch

Para gestionar el procesamiento de transacciones en diferido, PayCaddy aprovecha el procesamiento por lotes proporcionado por Mastercard y envía notificaciones a través de la ruta de notificación webhook convencional como parte de un proceso diario.

Estos webhooks facilitan la gestión de determinados tipos de transacciones. Los eventos que se notificarán mediante webhook como parte del proceso por lotes llevan los siguientes valores de campo "c1Tipo" :

  1. "TransaccionCorregidaPositiva": Se activa cuando una transacción es corregida positivamente, devolviendo saldo al monedero del usuario.
  2. "TransaccionCorregidaNegativa": Se activa cuando una transacción es corregida negativamente, retirando saldo del monedero del usuario.

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.

La mayoría de los webhooks relacionados con estas transacciones correctivas se enviarán durante el mismo periodo de la noche a la mañana.
Esto se debe a que nuestro proceso de generación de webhooks es un proceso por lotes que se ejecuta durante la noche para consolidar y notificar si hubo cambios en las transacciones del día.

{
 "password": "password",
 "c1Tipo": "TransaccionCorregidaPositiva",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

{
 "password": "password",
 "c1Tipo": "TransaccionCorregidaNegativa",
 "c2CardId": "cardId",
 "c3CodigoProceso": "000000",
 "c4ImporteTransaccion": "000000001617",
 "c7FechaHoraTransaccion": "20220429052901",
 "c11NumeroIdentificativoTransaccion": "000004339",
 "c18CodigoActividadEstablecimiento": "5999",
 "c19CodigoPaisAdquirente": "442",
 "c38NumeroAutorizacion": "040031",
 "c41TerminalId": "00227759",
 "c42Comercio": "227759000156182",
 "c43IdentificadorComercio": "AMZN Mktp ES             Amazon.ES"
}

En caso de recibir mensajes correctivos, como los de tipo "TransaccionCorregidaPositiva" y "TransaccionCorregidaNegativa", es imprescindible comunicarlo a los titulares de las tarjetas.

Estos mensajes implican que se ha modificado alguna de las transacciones originales del titular de la tarjeta o que se ha recibido una nueva transacción que no se recibió por la vía online habitual.Para mantener informados a los titulares de las tarjetas, debe comunicar las modificaciones que se han realizado en sus transacciones, destacando específicamente los importes que se están cargando o abonando en sus cuentas como consecuencia de estas correcciones.

Siempre que sea posible, se recomienda hacer coincidir 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 conocer 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.

Puede hacerlo con la información que viaja a través del campo "c11NumeroIdentificativoTransaccion".

Una vez modificada una transacción, no se volverá a modificar.

Aunque es menos común, también puede ocurrir que un cargo llegue sólo en el proceso por lotes y no en línea. Si este es el caso, el webhook puede llegar con menos información como se presenta a continuación. Cabe destacar que esta información es de acuerdo al protocolo de la red para el manejo de estas confirmaciones y no depende de PayCaddy.

{
 "type": "",
 "title": "currency code does not match target walletId",
 "status": 0,
 "detail": "",
 "instance": ""
}

Notificaciones de KYC Integrado

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.

{
 "metadata": {
   "userId": "string"
 },
 "status": "string",
 "description": "string",
 "fullName": "string",
 "age": "string",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Estados de verificación y descripciones

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

Flujo de validación KYC integrado y notificaciones webhooks.

Siguiendo este flujo de procesos, a continuación se muestran los webhooks correspondientes a cada estado.
Cada uno de estos webhooks proporciona una descripción del estado correspondiente, incluyendo las razones de rechazo en caso de verificaciones fallidas. Las descripciones correspondientes se detallan a continuación para su consulta.

‍Verification Inputs Completed: Este estado indica que un usuario ha completado con éxito la captura de datos KYC a través del kycURL y tendrá la estructura e información que se muestra a continuación:

{
"metadata": {
"userId": "unique user identifier"
},
"status": "verification_inputs_completed",
"description": "Ongoing verification",
"fullName": "Document OCR capture ongoing",
"age": "Document OCR capture ongoing",
"timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Verified: Este estado se refiere a cuando un usuario ha superado con éxito el proceso de verificación KYC. Esto indica que el usuario ha sido activado con éxito en nuestra base de datos y puede proceder con otros flujos de creación de tarjetas y operaciones. La respuesta del webhook tendrá la siguiente estructura e información:

{
 "metadata": {
   "userId": "ID único del usuario"
 },
 "status": "verified",
 "description": "Verification signed",
 "fullName": "User's full name",
 "age": "User's age",
 "timeStamp": "ISO 8601 format timestamp"
}

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.

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "Document doesn’t match input data",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "AML checks rejected",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The user is underage",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The document uploaded is expired",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "The document uploaded has issues",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "rejected",
 "description": "Validation Failed. User cannot be verified",
 "fullName": "User's complete name",
 "age": "null",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

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.

{
 "metadata": {
   "userId": "string"
 },
"status": "reviewNeeded",
 "description": "The document uploaded has issues",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
"status": "reviewNeeded",
 "description": "AML checks need to be reviewed",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "reviewNeeded",
 "description": "Government validation system inoperative",
 "fullName": "User's complete name",
 "age": "User's age",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

{
 "metadata": {
   "userId": "string"
 },
 "status": "reviewNeeded",
 "description": "Validation failed. Pending compliance review",
 "fullName": "User's complete name",
 "age": "null",
 "timeStamp": "2023-03-16T09:42:18.8338086Z"
}

Descubra cómo hacemos fintech más sencillo para Latinoamérica

Póngase en contacto con nosotros