Flujo de Contracargos en Sandbox

Estos endpoints te permiten simular el ciclo de un contracargo usando tus llaves de prueba. Todas las peticiones deben usar una llave de API de pruebas; una llave de producción no es válida contra estos endpoints de sandbox.

URL base: https://api.conekta.io

Autenticación y headers

Autentícate con HTTP Basic: tu llave privada de pruebas va como usuario y la contraseña queda vacía. En curl esto es -u "key_test_xxxx:" — los dos puntos finales son obligatorios. Incluye también el header de versión de la API:

Accept: application/vnd.conekta-v2.3.0+json

Para recibir los mensajes de error en un idioma fijo agrega Accept-Language: es (o en). En tu integración identifica los errores por los campos code y type de la respuesta, no por el texto de message.

Paso previo: crea un cargo pagado

Los endpoints de contracargo operan sobre un cargo (charge), no sobre la orden. Primero crea una orden pagada en sandbox; el identificador que usarás es el id del cargo dentro de charges.data[0].id (24 caracteres hexadecimales), no el ord_... de la orden.

curl -X POST https://api.conekta.io/orders \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "MXN",
    "customer_info": { "name": "Cliente de Prueba", "email": "[email protected]", "phone": "+5215555555555" },
    "line_items": [{ "name": "Producto de prueba", "unit_price": 15000, "quantity": 1 }],
    "shipping_lines": [{ "amount": 0, "carrier": "estafeta" }],
    "shipping_contact": {
      "phone": "+5215555555555",
      "receiver": "Cliente de Prueba",
      "address": { "street1": "Calle 123", "city": "CDMX", "state": "CDMX", "country": "MX", "postal_code": "06000" }
    },
    "charges": [{ "payment_method": { "type": "card", "token_id": "tok_test_visa_4242" } }]
  }'

Toma charges.data[0].id de la respuesta: ese es el charge_id para los siguientes pasos.

Crear contracargo

Abre un nuevo contracargo sobre un cargo existente.

POST /charges/{charge_id}/chargebacks

Parámetros de ruta

Cuerpo de la petición

curl -X POST https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json" \
  -H "Content-Type: application/json" \
  -d '{
    "acquirer": "bbva",
    "bank_reason": "4853",
    "case_number": "CASE-001"
  }'

Respuesta 201 Created

El contracargo nace en estado action_required.

{
  "id": "chbk_3aaLMNbci2BVGGDwu",
  "status": "action_required",
  "charge_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "created_at": "2025-04-17T10:30:25Z",
  "evidence_due_by": "2025-04-22T23:59:59Z"
}

acquirer, bank_reason y case_number se aceptan al crear el contracargo pero no se regresan en las respuestas de lectura.

Obtener contracargo

Devuelve el estado actual de un contracargo.

GET /charges/{charge_id}/chargebacks/{chargeback_id}

Parámetros de ruta

curl https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json"

Respuesta 200 OK

{
  "id": "chbk_3aaLMNbci2BVGGDwu",
  "status": "action_required",
  "charge_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "created_at": "2025-04-17T10:30:25Z",
  "evidence_due_by": "2025-04-22T23:59:59Z"
}

Obtener transiciones disponibles

Devuelve la lista de estados a los que puede moverse el contracargo desde su estado actual. Consúltalo antes de cada cambio de estado para saber qué transición es válida.

GET /charges/{charge_id}/chargebacks/{chargeback_id}/transitions

Parámetros de ruta

curl https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu/transitions \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json"

Respuesta 200 OK

Recién creado (estado action_required), la única transición disponible es represented:

[
  { "state_to": "represented" }
]

El resultado es un conjunto (el orden no está garantizado). Un arreglo vacío indica que no hay más transiciones disponibles desde el estado actual.

Actualizar estado del contracargo

Transiciona un contracargo a un nuevo estado para simular el avance de la disputa.

PATCH /charges/{charge_id}/chargebacks/{chargeback_id}

Parámetros de ruta

Cuerpo de la petición

Primero crea la representación (action_required → represented):

curl -X PATCH https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "represented"
  }'

Luego resuelve la disputa a favor del comercio (represented → won):

curl -X PATCH https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -u "key_test_xxxx:" \
  -H "Accept: application/vnd.conekta-v2.3.0+json" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won"
  }'

Respuesta 204 No Content

Sin cuerpo en la respuesta.

El flujo de simulación

En sandbox el flujo que puedes simular es:

action_required  →  represented  →  won

Consulta siempre /transitions antes de un PATCH: solo son válidos los estados que ese endpoint devuelve desde el estado actual. Para el ciclo de vida completo de un contracargo real, consulta Qué son los contracargos.

Errores