Los campos que la mayoría de integraciones omiten en el charge request de Kushki y que están bajando tu tasa de aprobación en LATAM

La mayoría de integraciones con la API de Kushki arrancan igual: token, monto, moneda — y a producción. Funciona. Pero hay una brecha silenciosa entre 'funciona' y 'aprueba al máximo posible'.

Los emisores bancarios en LATAM no aprueban transacciones basándose solo en si hay fondos disponibles. Evalúan el nivel de información que reciben con cada request. A más contexto, menor riesgo percibido, mayor tasa de aprobación. Este artículo detalla los campos que más impacto tienen y que la mayoría de integraciones omite.

El charge request mínimo vs. el charge request optimizado

Este es el request que envían la mayoría de integraciones en su primera versión:

1POST /v1/charges
2{
3  "token": "xkT8abc123...",
4  "amount": {
5    "subtotalIva0": 1200.00,
6    "currency": "MXN"
7  }
8}

Funciona. Pero le estás dando al emisor la información mínima para tomar una decisión — y en casos de duda, los emisores rechazan.

Este es el mismo request optimizado:

1POST /v1/charges
2{
3  "token": "xkT8abc123...",
4  "amount": {
5    "subtotalIva0": 1200.00,
6    "currency": "MXN"
7  },
8  "fullResponse": true,
9  "metadata": {
10    "billingDetails": {
11      "name": "Ana García",
12      "email": "ana@empresa.com",
13      "phone": "5512345678",
14      "address": "Av. Insurgentes 123",
15      "city": "Ciudad de México",
16      "country": "MX",
17      "zipCode": "06600"
18    },
19    "orderDetails": {
20      "orderId": "ORD-8821",
21      "productDetails": [
22        {
23          "id": "PROD-001",
24          "name": "Suscripción Pro",
25          "quantity": 1,
26          "unitPrice": 1200.00
27        }
28      ]
29    }
30  }
31}

La diferencia en tasa de aprobación entre estos dos requests puede ser de 5 a 15 puntos porcentuales dependiendo del país y el tipo de tarjeta — especialmente en transacciones internacionales y tickets altos.

Campo por campo: qué hace cada uno

fullResponse: true

Sin este campo, Kushki devuelve solo el resultado final de la transacción. Con él, recibes la respuesta completa del emisor incluyendo el declineCode cuando hay un rechazo. Es imprescindible para diagnóstico — sin él, no puedes saber por qué están fallando tus transacciones.

1// Sin fullResponse
2{ "ticketNumber": "TRX-001", "status": "DECLINED" }
3
4// Con fullResponse
5{
6  "ticketNumber": "TRX-001",
7  "status": "DECLINED",
8  "declineCode": "61",
9  "declineMessage": "Exceeds withdrawal amount limit"
10}

billingDetails

Es el campo con mayor impacto en aprobación. Los emisores, especialmente en México y Colombia, validan la dirección de facturación contra sus registros. Un match parcial reduce la probabilidad de rechazo por sospecha de fraude.

El campo más importante dentro de billingDetails es zipCode — es el que los emisores usan con mayor frecuencia para validación de dirección (AVS). Si solo puedes recolectar un campo adicional en tu checkout, que sea ese.

orderDetails

Proporciona contexto sobre qué se está comprando. Los modelos antifraude de los emisores — y el de Kushki — usan esta información para evaluar si la transacción es consistente con el comportamiento típico del tarjetahabiente. Una transacción sin contexto de producto se ve más sospechosa que una con detalle de la orden.

Ajustes específicos por país

El impacto de cada campo varía por mercado. Esta es la priorización recomendada:

México: El AVS (Address Verification System) es activo en la mayoría de bancos mexicanos. Prioriza zipCode y address en billingDetails. Para transacciones B2B, incluye también el RFC del pagador si lo tienes disponible.

Colombia: Los emisores colombianos dan más peso a la identidad del pagador que a la dirección. Asegúrate de que el name en billingDetails coincida exactamente con el nombre del titular de la tarjeta. Una discrepancia aquí activa flags antifraude en varios bancos colombianos.

Chile: El mercado chileno tiene emisores con modelos antifraude más conservadores para e-commerce. El email del pagador tiene peso adicional — es uno de los campos que los bancos chilenos usan para correlacionar transacciones con el historial del usuario.

El error de implementación más frecuente

El campo metadata se envía vacío o con datos genéricos porque el equipo técnico no tiene acceso a esa información en el momento del charge.

La solución es arquitectural: asegúrate de que cuando tu backend procesa el charge, tiene acceso a los datos del usuario y de la orden — no solo al token y al monto. Si tu flujo de pago separa la tokenización del checkout del charge final, pasa la información de contexto como parte del payload.

1// Mal: charge con contexto mínimo
2const charge = await kushkiClient.charge({
3  token: req.body.token,
4  amount: req.body.amount
5});
6
7// Bien: charge con contexto completo
8const charge = await kushkiClient.charge({
9  token: req.body.token,
10  amount: req.body.amount,
11  fullResponse: true,
12  metadata: {
13    billingDetails: req.body.billingDetails, // pasado desde el frontend
14    orderDetails: buildOrderDetails(req.body.orderId) // construido en backend
15  }
16});

Optimizar el charge request no requiere cambiar tu arquitectura ni rediseñar el checkout. Son campos adicionales en un request que ya estás haciendo. El retorno — en términos de transacciones aprobadas — justifica con creces el esfuerzo de implementación.

Para la referencia completa del endpoint de charges y todos los campos disponibles, visita la documentación de Kushki.