API de Evidencia de Contracargos

Con esta API puedes consultar qué evidencia requiere un contracargo y subir la
documentación para representarlo, es decir, para defender la disputa ante el banco.

La evidencia se sube en lote (batch): en una sola petición envías todos los
tipos de evidencia requeridos. Cuando la carga es exitosa, el contracargo pasa
automáticamente al estado pending_review.

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

Autenticación

Todas las peticiones usan HTTP Basic Auth. Envía tu llave privada (Private API
Key) como usuario y deja la contraseña vacía.

Authorization: Basic base64(API_KEY:)

curl -u key_xxxxxxxxx: https://api.conekta.io/...

El flag -u key_xxxxxxxxx: de cURL genera el header Authorization: Basic ...
(con base64) automáticamente. Los dos puntos finales indican contraseña vacía.

Si envías la petición sin credenciales válidas, recibirás un 401 Unauthorized.

Tipos de evidencia

Cada contracargo exige un conjunto de tipos de evidencia. Algunos son
obligatorios (required: true) y otros opcionales. La lista exacta puede
variar según el adquirente y el motivo (reason code) del contracargo, por lo que
siempre debes consultarla con GET /evidence-types antes de subir.

Endpoints

Parámetros de ruta (todos los endpoints)

1. Obtener tipos de evidencia

Obtén la lista de tipos de evidencia que aplican al contracargo. Cada tipo indica si
es obligatorio y qué formatos de archivo acepta.

Llama este endpoint antes de subir evidencia para saber exactamente qué tipos
debes incluir.

GET /charges/{charge_id}/chargebacks/{chargeback_id}/evidence-types

Ejemplo

curl -X GET \
  "https://api.conekta.io/charges/{charge_id}/chargebacks/{chargeback_id}/evidence-types" \
  -u key_xxxxxxxxx:

Response 200 OK

Recibes un arreglo de objetos de tipo de evidencia.

[
  { "type": "order_details",          "permit_formats": ["pdf"], "required": true },
  { "type": "terms_and_conditions",   "permit_formats": ["pdf"], "required": true },
  { "type": "cardholder_information", "permit_formats": ["pdf"], "required": true },
  { "type": "proof_invalidate_claim", "permit_formats": ["pdf"], "required": true },
  { "type": "charge_information",     "permit_formats": ["pdf"], "required": true },
  { "type": "contract",               "permit_formats": ["pdf"], "required": false },
  { "type": "receipt_of_shipment",    "permit_formats": ["pdf"], "required": false },
  { "type": "internal_validations",   "permit_formats": ["pdf"], "required": false }
]

2. Listar archivos del contracargo

Lista todos los archivos ya asociados al contracargo, incluidos los que genera el
sistema automáticamente.

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

Ejemplo

curl -X GET \
  "https://api.conekta.io/charges/{charge_id}/chargebacks/{chargeback_id}/files" \
  -u key_xxxxxxxxx:

Response 200 OK

Recibes un arreglo directo de archivos (sin envoltura data).

[
  {
    "id": "chbkf_31HEQaaYvKUw8K3qY",
    "name": "20260602100000000000004.pdf",
    "created_at": "2026-06-25T14:29:45Z",
    "evidence_type": "charge_information"
  }
]

3. Obtener un archivo específico

Obtén la metadata de un archivo más una URL de descarga prefirmada.

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

Ejemplo

curl -X GET \
  "https://api.conekta.io/charges/{charge_id}/chargebacks/{chargeback_id}/files/{file_id}" \
  -u key_xxxxxxxxx:

Response 200 OK

{
  "id": "chbkf_31HEQaaYvKUw8K3qY",
  "name": "20260602100000000000004.pdf",
  "created_at": "2026-06-25T14:29:45Z",
  "evidence_type": "charge_information",
  "url": "https://.../evidence/...?X-Amz-Algorithm=...&X-Amz-Expires=900&X-Amz-Signature=..."
}

4. Subir evidencia en lote (batch) — recomendado

Sube uno o más archivos de evidencia en una sola petición. Todos los tipos
marcados como required en GET /evidence-types deben estar presentes —ya sea en
este batch o por un archivo previo en GET /files— de lo contrario la petición se
rechaza con un 422.

Cuando la carga es exitosa, el contracargo pasa automáticamente al estado
pending_review.

POST /charges/{charge_id}/chargebacks/{chargeback_id}/files/batch

Petición

• Content-Type: multipart/form-data
• El nombre de cada campo del formulario debe coincidir con un type de
  GET /evidence-types.
• Puedes enviar exactamente un archivo por tipo de evidencia.

Restricciones de archivo

Ejemplo

curl -X POST \
  "https://api.conekta.io/charges/{charge_id}/chargebacks/{chargeback_id}/files/batch" \
  -u key_xxxxxxxxx: \
  -F "order_details=@order_details.pdf;type=application/pdf" \
  -F "[email protected];type=application/pdf" \
  -F "[email protected];type=application/pdf" \
  -F "[email protected];type=application/pdf"

En el ejemplo se omite charge_information porque ya existía como archivo
generado automáticamente en el contracargo. Por eso el batch se acepta aunque no
reenvíes ese tipo.

Response 200 OK

Recibes la lista de archivos subidos, bajo la clave files.

{
  "files": [
    {
      "id": "chbkf_31HEk8nqQr6uPuzq4",
      "name": "terms.pdf",
      "created_at": "2026-06-25T14:55:22.976Z",
      "evidence_type": "terms_and_conditions",
      "url": "https://.../evidence/terms.pdf?X-Amz-Expires=...&X-Amz-Signature=..."
    }
  ]
}

Errores

Ejemplo 422 — faltan tipos obligatorios

Cuando falta evidencia obligatoria, el response te indica qué tipos faltan para que
puedas pedírselos a tu cliente.

{
  "object": "error",
  "type": "resource_error",
  "details": [
    {
      "code": "conekta.errors.business.chargebacks.missing_mandatory_evidence_types",
      "message": "The following mandatory evidence types are missing: cardholder_information, charge_information",
      "param": null
    }
  ]
}

5. Subir un archivo individual

Sube un solo archivo de evidencia. Te sirve para casos puntuales, pero para la
representación te recomendamos el batch (#4), ya que valida en una sola operación
que estén todos los tipos obligatorios.

POST /charges/{charge_id}/chargebacks/{chargeback_id}/files

Petición

• Content-Type: multipart/form-data

Ejemplo

curl -X POST \
  "https://api.conekta.io/charges/{charge_id}/chargebacks/{chargeback_id}/files" \
  -u key_xxxxxxxxx: \
  -F "type=order_details" \
  -F "file=@order_details.pdf;type=application/pdf"

Igual que el batch, solo procede si el contracargo está en estado
action_required. Si ya está en pending_review, recibirás un 400
(conekta.errors.business.chargebacks.cannot_process).

Flujo recomendado

1. GET  /evidence-types   → Conoce los tipos obligatorios y opcionales del contracargo
2. GET  /files            → Revisa los archivos ya adjuntos (incluye los automáticos)
3. Cruza las listas       → Quita de los requeridos los tipos ya cubiertos
4. Reúne los archivos     → Solo de los tipos requeridos que aún faltan
5. POST /files/batch      → Sube todo en una sola petición

Si te saltas el paso 2 puedes recibir un 400 por tipo de evidencia duplicado,
ya que algunos archivos (p. ej. charge_information) los genera el sistema antes de
que subas algo.

Formato de errores

Todos los errores siguen el envelope estándar de Conekta:

{
  "object": "error",
  "log_id": "6a3d3ec723a11a001abb2dc1",
  "type": "<error_type>",
  "details": [
    {
      "code": "<error_code>",
      "message": "<mensaje_legible>",
      "param": "<campo_si_aplica>"
    }
  ]
}

El campo message se localiza según el header Accept-Language. El campo code
siempre viene en inglés.

Buenas prácticas para tu evidencia

Para mejorar tu probabilidad de ganar la disputa, te recomendamos:

• Incluir comprobante de entrega con firma.
• Mostrar la IP address o los datos del dispositivo.
• Adjuntar la confirmación de compra que enviaste a tu cliente.
• Incluir los términos y condiciones aceptados.
• Adjuntar la comunicación con tu cliente.