Por qué el mismo request a la API de Kushki produce tasas de aprobación distintas en México, Colombia y Chile — y cómo usar los códigos de error para diagnosticarlo

Tienes la misma integración corriendo en tres países. En México aprueba el 85% de las transacciones. En Colombia el 71%. En Chile el 78%. El código es idéntico, entonces, ¿qué está pasando?

La respuesta casi siempre está en los códigos de error que recibes y en lo que le mandas al emisor. Este artículo explica cómo leer los rechazos de la API de Kushki para diagnosticar problemas de aprobación por mercado.

Los rechazos no son todos iguales

Cuando una transacción falla, Kushki devuelve un code y un message en el cuerpo del error. El error que más se ignora en las integraciones es la diferencia entre un rechazo de la plataforma y un rechazo del emisor — y son dos problemas completamente distintos.

1// Rechazo de la plataforma (error de integración)
2{
3  "code": "K001",
4  "message": "Invalid request body"
5}
6
7// Rechazo del emisor (el banco rechazó la tarjeta)
8{
9  "code": "K003",
10  "message": "Card declined by issuer",
11  "declineCode": "51"
12}

Los rechazos de plataforma (K001, K002) son errores que tú puedes corregir en tu código. Los rechazos de emisor (K003) dependen del banco del tarjetahabiente — pero hay cosas que puedes hacer para reducirlos.

Los códigos de emisor que más afectan la aprobación por país

El declineCode dentro de un K003 es el código que devuelve el banco emisor. Estos son los más frecuentes en LATAM y su significado en contexto:

• Código 51 (Insufficient funds): El más común en todos los mercados. Poco que hacer desde la integración — el usuario no tiene fondos.

• Código 54 (Expired card): La tarjeta expiró. Si tu checkout no valida la fecha antes de tokenizar, estarás viendo este código con más frecuencia de lo que deberías.

• Código 61 (Exceeds withdrawal amount limit): Límite de monto excedido. En Colombia afecta desproporcionadamente a las tarjetas débito — los límites diarios de débito en bancos colombianos son considerablemente más bajos que los de crédito. Si tu producto tiene tickets altos y tus usuarios en CO usan débito, considera guiarlos a crédito o transferencia.

• Código 65 (Exceeds withdrawal frequency limit): Límite de frecuencia excedido. Especialmente relevante en Chile — muchos bancos chilenos tienen límites de frecuencia más estrictos para pagos contactless y en línea. Si tus usuarios en CL intentan pagar varias veces seguidas, este código es indicativo.

Lo que puedes controlar: los campos que mejoran la aprobación

Los emisores no aprueban solo basándose en si hay fondos disponibles. Evalúan el nivel de información que reciben con la transacción. A más datos, menor riesgo percibido, mayor probabilidad de aprobación.

Estos son los campos que más impacto tienen y que las integraciones frecuentemente omiten:

1POST /v1/charges
2{
3  "token": "xkT8...",
4  "totalAmount": 1200.00,
5  "currency": "MXN",
6
7  // Estos campos mejoran la aprobación — no son opcionales en práctica
8  "fullResponse": true,
9  "metadata": {
10    "billingDetails": {
11      "name": "Ana García",
12      "email": "ana@email.com",
13      "phone": "5512345678",
14      "address": "Av. Insurgentes 123",
15      "city": "Ciudad de México",
16      "country": "MX",
17      "zipCode": "06600"
18    }
19  }
20}

fullResponse: true le dice a Kushki que devuelva la respuesta completa del emisor, incluyendo el declineCode. Sin este flag, solo recibes el resultado final y pierdes la información que necesitas para diagnosticar rechazos.

Los billingDetails completos reducen los rechazos por sospecha de fraude, especialmente en transacciones internacionales o de ticket alto. En México, la dirección de facturación tiene peso adicional porque los emisores la usan para AVS (Address Verification System).

Cómo estructurar el diagnóstico por país

Si tienes tasas de aprobación distintas por mercado, este es el proceso para identificar la causa:

Paso 1 — Segmenta los errores por code y declineCode

Agrupa tus transacciones fallidas por país y por código. Si la mayoría de rechazos en un país son K001 o K002, el problema es tu integración. Si son K003, el problema es el emisor — y necesitas el declineCode para saber exactamente cuál.

Paso 2 — Revisa si estás enviando fullResponse: true

Sin este campo no tienes declineCode y el diagnóstico es a ciegas.

Paso 3 — Identifica patrones por declineCode

1// Ejemplo de agrupación básica para diagnóstico
2const declineSummary = transactions
3  .filter(t => t.status === 'DECLINED')
4  .reduce((acc, t) => {
5    const key = `${t.country}-${t.declineCode}`;
6    acc[key] = (acc[key] || 0) + 1;
7    return acc;
8  }, {});
9
10console.log(declineSummary);
11// { 'MX-54': 23, 'CO-61': 41, 'CL-65': 17, ... }

Paso 4 — Aplica la corrección específica

Con los patrones identificados: si ves muchos 54 (expired card), mejora la validación en el frontend. Si ves muchos 61 en CO, evalúa si tu audiencia usa principalmente débito y considera ofrecer transferencia PSE como alternativa. Si ves 65 en CL, revisa si estás intentando el pago más de una vez en la misma sesión.

La tasa de aprobación no es solo un número de negocio — es un indicador directo de qué tan bien está configurada tu integración. Los códigos de error de Kushki te dan la información para mejorarla, pero solo si los estás leyendo correctamente.

Para la referencia completa de códigos de error por país, consulta la documentación de Kushki.