Al integrar y consumir los servicios web de Payphone, pueden surgir errores que impidan completar una transacción.
A continuación, te presentamos una guía con los errores más comunes y cómo manejarlos.
Estos errores se presentan cuando la transacción se genera correctamente, pero el banco emisor rechaza su procesamiento. Esto puede ocurrir por diversas razones, como:
Importante:
StatusCode el número 2 (que significa "Cancelado").message, recibirás la descripción del error para que se la muestres al usuario final.Mensajes Específicos del Emisor y su Acción Correspondiente 👇
A continuación, te detallamos los posibles mensajes que el banco emisor puede entregar, junto con la acción que debes tomar:
Mensaje
Acción
Fondos Insuficientes 💰
El banco rechazó la transacción por falta de dinero. El StatusCode será 2 (Cancelado).
Fecha incorrecta 🗓️
La fecha de caducidad ingresada no es correcta. El cliente debe validar que la fecha esté bien o contactar a su banco emisor para verificar el motivo del mensaje.
CVV o código inválido 🔒
El código de seguridad (el número de 3 dígitos en la parte trasera de la tarjeta) ingresado no es correcto. El cliente debe validar que lo haya ingresado bien o verificar con su banco emisor por qué se presenta este mensaje.
Transacción rechazada ⛔
El banco emisor del cliente simplemente rechazó la transacción. El cliente debe contactarse con su banco para verificar el motivo exacto del rechazo.
Transacción Inválida 🔄
Primero, debes verificar si el monto enviado es correcto. Si los valores son correctos, esto implica que el banco emisor del cliente rechazó la transacción, y este debe contactarse con ellos para verificar el motivo del rechazo.
Diferido no autorizado 🚫
La opción de pago diferido que se intentó usar no está autorizada por el comercio.
Monto excedido 💲
El monto de la transacción que se intentó enviar excede el límite máximo configurado por el comercio para sus transacciones.
La tarjeta que el cliente intenta usar tiene una alerta grave de seguridad con su banco emisor. El cliente debe contactar a su banco y verificar el error. Cuando se presenta este mensaje, Payphone añade automáticamente al usuario a listas de control para la autorización o negación de transacciones futuras, por seguridad.
Estos errores ocurren cuando tu petición (llamada) al servicio web de Payphone no cumple con los requisitos, tiene fallos de validación o simplemente hubo un problema en el procesamiento de tu solicitud.
En estos casos, recibirás un ErrorCode que te indicará exactamente qué salió mal. ¡Aquí te explicamos cada uno y qué puedes hacer al respecto! 👇
ErrorCode
📝 Descripción del Problema
Acción Sugerida ✅
1
La aplicación no existe, verifique que el token enviado sea el entregado para su aplicación.
Verifica que el token enviado sea el correcto.
4
La aplicación no tiene relación con la compañía especificada.
Revisa la relación entre tu app y la compañía configurada.
5
Su dominio no está autorizado por la aplicación. Ingrese a la consola de developer para configurar.
Ingresa a la consola de developer y añade tu dominio.
6
Usted no tiene permisos para acceder a esta funcionalidad. Por favor póngase en contacto con Payphone.
Contacta a Payphone para habilitar el acceso.
20
La transacción no existe, verifique que el identificador enviado sea correcto.
Verifica que el identificador enviado sea correcto.
21
La transacción que desea anular/reversar no existe.
Asegúrate de que el ID de transacción enviado es válido y corresponde a una operación reversible.
22
La transacción no pudo ser creada, por favor inténtelo de nuevo.
Intenta nuevamente más tarde; si persiste, contacta al soporte.
23
Ya existe una transacción con el ClientTransactionId especificado.
Cambia el identificador; cada transacción debe tener un ID único.
24
La transacción ya se encuentra cancelada.
Verifica el estado de la transacción antes de intentar cancelarla.
25
La transacción no se pudo cancelar. Puede que ya se encuentre aprobada o cancelada.
Asegúrate de que no esté ya aprobada o cancelada.
26
Solo se permiten {0} transacciones por día para la misma tarjeta. Por favor póngase en contacto con la persona encargada de la tienda.
Contacta al administrador de la tienda para revisar restricciones.
40
La transacción no es un reverso.
Verifica el tipo de transacción antes de enviar el reverso.
42
El reverso no se puede ejecutar. Contáctese con el banco emisor de la tarjeta del usuario para completar el proceso.
Contacta al banco emisor del cliente para resolverlo.
60
La anulación no existe, verifique que el identificador enviado sea correcto.
Verifica el ID de la transacción de anulación.
61
La transacción solicitada no es una anulación, verifique el identificador enviado.
Asegúrate de enviar el identificador correcto.
62
La anulación no pudo ser creada. Consulte al banco emisor de la tarjeta del cliente para completar el proceso.
Consulta con el banco emisor del cliente.
100
La tienda asociada no existe. Verifique su store id o comuníquese con Payphone.
Verifica el Store ID o contacta a Payphone.
101
El terminal enviado no está asociado a la tienda que atiende el pago.
Asegura que el terminal esté registrado correctamente en la tienda.
102
El monto máximo por transacción para este local es de {0} {1}.
Revisa la configuración de montos máximos para esa tienda.
103
La tienda no tiene las configuraciones de montos para realizar esta transacción.
Configura los límites de monto en la consola de Payphone.
120
El usuario no existe en Payphone.
Verifica los datos del usuario (teléfono o identificador).
121
La moneda especificada no es soportada actualmente. Verifique el catálogo de monedas soportadas.
Consulta el catálogo de monedas permitidas por Payphone.
125
Existen dos usuarios con el mismo nickname. Por favor envíe la venta mediante el número de teléfono.
Enviar la transacción usando el número de teléfono del usuario.
127
No fue posible completar el pago. Para más información comuníquese con Payphone.
El usuario podría estar en una lista de control antifraude. Contacta a Payphone para desbloquear.
500
La solicitud no pudo ser completada. Por favor inténtelo de nuevo.
Intenta de nuevo; si persiste, contacta soporte.
501
El servicio no está disponible, intente de nuevo por favor.
Intenta nuevamente después de unos minutos.
600
Las peticiones requieren protocolo seguro https.
Asegura que la llamada se haga usando el protocolo HTTPS.
800
Validaciones fallidas.
Revisa el arreglo con los errores específicos en la respuesta y corrígelos.
802
El token especificado no es válido. Por favor solicite un nuevo token.
Solicita un nuevo token desde la consola de desarrolladores.
820
La tarjeta no existe.
Revisa que el número de tarjeta enviado sea válido y esté completo.
821
Código de Verificación Inválido.
Verifica que el CVV ingresado sea correcto.
822
Bin de tarjeta inválido. Generalmente porque el valor enviado es menor de 6 caracteres.
Asegúrate de enviar un BIN válido (mínimo 6 dígitos).
823
Tipo de diferido es inválido. Este campo debe tener una longitud de 10 caracteres.
Revisa que el campo tenga 10 caracteres y esté bien formado.
824
La tienda no tiene el diferido enviado.
Verifica la configuración de tipos de diferido para la tienda.
825
El diferido no está activo para la tienda, por favor póngase en contacto con su vendedor.
Solicita al vendedor activar este tipo de diferido.
900
El probador no es parte de la aplicación actual.
Verifica que el tester esté registrado correctamente.
901
El probador no se encuentra activo.
Activa al tester desde la consola de desarrolladores.
1001
Esta solicitud no cumple los parámetros necesarios
Verificar q los campos de cadenas de caracteres ese envie entre ""
1004
Su aplicación no está autorizada para acceder a este recurso. Verifique que el token esté bien copiado o a qué recursos puede acceder su tipo de aplicación.
Revisa el tipo de token y los permisos configurados para tu aplicación.
..
No HTTP resource was found that matches the request URI 'https://pay.payphonetodoesposible.com/api/xxxxxx/xxxxxx'.
URL del EndPoint incorrecta. Verificar q la URL del Endpoint sea la correcta
⚠️ Errores Especiales a Considerar
🔐 Error 800 – Validaciones Fallidas
Si obtienes el error 800 de validaciones fallidas, encontrarás un arreglo adentro indicando el o los errores generados.
🔒 Error 127 – Usuario en Lista de Control Antifraude
El error 127 de “No fue posible completar el pago. Para más información comuníquese con Payphone” implica que el usuario está en nuestras listas de control antifraude debido a un intento de pago sospechoso o a usar datos falsos en sus peticiones.
Debes contactar con nuestro equipo de soporte para verificar el bloqueo del usuario.
ErrorCode 800: ¡Detalle Extendido de Validaciones Fallidas! 🚧Cuando recibes el ErrorCode 800 ("Validaciones fallidas"), significa que tu solicitud a Payphone no cumple con los requisitos esperados en uno o más campos. La buena noticia es que Payphone te enviará un arreglo (array) dentro de la respuesta llamado "errors", que te indicará exactamente qué campos fallaron y por qué.
Ejemplo de Respuesta de Error:
{
"message": "Validaciones fallidas",
"errorCode": 800,
"errors": [
{
"message": "Amount",
"errorCode": 0,
"errorDescriptions": [
"El campo Amount no es igual a la suma de AmountWithTax, AmountWithoutTax, Tax, Service, Tip"
]
}
]
}Para ayudarte a resolver estos problemas rápidamente, aquí tienes una tabla con los detalles de cada validación fallida, la descripción exacta que Payphone te devuelve y las acciones que puedes tomar:
🔧 Parámetro
⚠️ Descripción de error
✅ Acción Sugerida
Amount
El campo Amount no es igual a la suma de AmountWithTax, AmountWithoutTax, Tax, Service, Tip
Asegúrate de que el valor en el campo Amount sea exactamente la suma de todos los demás componentes monetarios:
AmountWithTax + AmountWithoutTax + Tax + Service + Tip.
Aunque algunos de estos campos son opcionales, al menos uno debe estar presente para respaldar el monto total.
El Amount debe ser un entero entre 1 y 99999999
Todos los montos deben expresarse como enteros y en centavos. Si tu valor es, por ejemplo, $10.50, debes enviarlo como 1050. Multiplica siempre el valor en dólares por 100.
Para generar un link sin valor definido, el monto debe ser 0.
Si tu intención es crear un link de pago con un monto editable por el usuario (es decir, sin un valor predefinido), debes enviar el campo Amount con el valor 0 u omitir todos los campos de montos (como Amount,AmountWithTax, Tax, etc.).
AmountWithTax
Si el campo AmountWithTax tiene valor entonces Tax debe tener un valor
Si incluyes un valor en AmountWithTax (monto sujeto a impuestos sin incluir el impuesto), entonces el campo Tax (el impuesto aplicado) debe tener un valor definido. Ambos van de la mano.
Tax
Si el campo Tax tiene valor entonces AmountWithTax debe tener un valor
Si defines un valor para el campo Tax (el monto del impuesto), entonces el campo AmountWithTax (el monto sujeto a ese impuesto) debe tener un valor también. No puede haber impuesto sin una base imponible.
ClientTransactionID
El campo ClientTransactionId no debe exceder los 50 caracteres
Tu identificador único de transacción (ClientTransactionId) es demasiado largo. Asegúrate de que no supere los 50 caracteres. Cámbialo por uno más corto y único.
Reference
El campo Reference no debe exceder los 100 caracteres
El campo de referencia de tu transacción es muy largo. Reduce su longitud para que no supere los 100 caracteres.
Currency
El campo Currency no debe exceder los 3 caracteres
El código de moneda que enviaste es incorrecto o tiene más de 3 caracteres. Usa el código ISO 4217 de 3 caracteres (por ejemplo, USD para Dólar estadounidense).
ResponseUrl
Campo obligatorio.
Si estás creando un botón de pagos por redirección, el campo ResponseUrl es obligatorio. Es la URL a la que Payphone debe redireccionar al usuario después de completar el pago. Asegúrate de incluirla.
PhoneNumber
Número de teléfono inválido
El formato del número de teléfono es incorrecto. Debe comenzar con el símbolo +, seguido del código de país y luego el número telefónico. Ejemplo: +593984111222.
Número de teléfono inválido o codigo pais invalido
Para la API Sale, el formato del número de teléfono debe ser 0 seguido del número telefónico (0984111222). El código de país debe ser el estándar E.164 (ej: 593). Revisa ambos.
Correo electrónico inválido
El formato del correo electrónico es incorrecto. Debe ser un formato válido como ejemplo@dominio.com. Verifica que no haya espacios ni caracteres especiales.
TimeZone
El TimeZone debe ser un entero entre -12 y 14
El valor que proporcionaste para la zona horaria (TimeZone) está fuera del rango permitido. Debe ser un número entero entre -12 y 14.
Lat
El Lat debe ser un entero entre -90 y 90
La latitud (Lat) que enviaste está fuera de los límites geográficos válidos. Debe ser un número entero entre -90 y 90.
Lng
El Lng debe ser un entero entre -180 y 180
La longitud (Lng) que enviaste está fuera de los límites geográficos válidos. Debe ser un número entero entre -180 y 180.
CardHolder
La cadena debe ser un base 64 válida
Asegúrate de codificar el nombre del titular en base64, encriptado con AES-256-CBC sin vector de inicialización.
BillTo
Número de teléfono inválido
El formato del número de teléfono del receptor (BillTo) es incorrecto. Debe seguir el formato: + + Código de País + número telefónico. Ejemplo: +593984111222.
Correo electrónico inválido
El formato del correo electrónico del receptor (BillTo) es incorrecto. Debe ser un formato válido como ejemplo@dominio.com.
TransferTo
Impossible to decode the data.
Los datos encriptados para la transferencia tienen un error. Verifica que la contraseña de codificación sea correcta y que la encriptación AES 256 CBC sin vector de inicialización se esté realizando adecuadamente.
Identifier
La compañía XXXXXXXXXX001 no existe o no cuenta con una billetera en la cual depositar
La compañía a la que intentas distribuir el monto no está registrada en Payphone o no tiene una billetera activa. Confirma el identificador de la compañía y su estado en Payphone.
Error Interno: 3084
El monto por pagar es superior al saldo disponible
El monto que intentas pagar excede el saldo disponible en la cuenta del comercio. Asegúrate de que el monto de la transacción no supere el saldo actual del comercio.
Error Interno: 3185
No fue posible realizar el pago en lote. Usted ya cuenta con uno procesando.
Ya hay un proceso de pago en lote activo. Verifica que los estados de tus lotes de pagos masivos estén finalizados correctamente antes de iniciar uno nuevo.
N/A
Compañía no tiene permitido realizar pagos masivos.
Tu aplicación o compañía no tiene la autorización para realizar pagos masivos. La aplicación de tipo "pago" debe estar autorizada por el usuario autorizador en tu cuenta Payphone. Contacta con tu administrador para habilitarlo.
Error Interno: 3236
Permitir Registro de Tienda Personal
Para procesar este tipo de transacción, debes registrarte en la web de Payphone como "Comercio Personal" .
CompanyCode
Ruc/Nit ya registrado
El número de RUC/NIT que intentas registrar ya existe en Payphone. Si ya tienes una cuenta, úsala. Si crees que es un error, contacta a Payphone.
Ruc/Nit incorrecto
El número de RUC/NIT que ingresaste es inválido. Asegúrate de introducir un RUC/NIT correcto y válido.
N/A
Impossible to decode the data
El nombre del titular está encriptado con una contraseña diferente a la configurada en tu aplicación o la encriptación no es correcta. Revisa la contraseña de codificación y tu proceso de encriptación.
N/A
Could not convert string to integer: xxxx.
Estás enviando un valor de tipo texto (cadena de caracteres) a un campo que espera un número entero. Asegúrate de que los campos numéricos solo reciban valores numéricos.