DocumentaciónAPIDevToolsRecipesTarjetas de PruebasEstado del ServicioChangelog
Documentación
Iniciar Sesión

Flujo de Contragargos en Sandbox

Estos endpoints te permiten simular el ciclo completo de un contracargo usando tus llaves de prueba. Todas las peticiones deben usar una llave de API de pruebas. Enviar una llave de producción devuelve 403 Forbidden.

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

Crear contracargo

Abre un nuevo contracargo sobre un cargo existente.

POST /charges/{charge_id}/chargebacks

Parámetros de ruta

ParámetroTipoRequeridoDescripción
charge_idstringSíID del cargo (ej. a1b2c3d4e5f6a7b8c9d0e1f2)

Cuerpo de la petición

CampoTipoRequeridoDescripción
acquirerstringSíBanco que emitió el contracargo. Valores: amex, banorte, bbva, afirme, banregio, conekta
bank_reasonstringNoCódigo de razón del banco (ej. 4853)
case_numberstringNoNúmero de caso o referencia del banco
curl -X POST https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks \
  -H "Authorization: Bearer key_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "acquirer": "bbva",
    "bank_reason": "4853",
    "case_number": "CASE-001"
  }'

Respuesta 201 Created

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

updated_at devuelve el valor cero (0001-01-01T00:00:00Z) cuando el contracargo aún no ha sido actualizado.

Obtener contracargo

Devuelve el estado actual de un contracargo.

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

Parámetros de ruta

ParámetroTipoRequeridoDescripción
charge_idstringSíID del cargo (ej. a1b2c3d4e5f6a7b8c9d0e1f2)
chargeback_idstringSíID del contracargo (ej. chbk_3aaLMNbci2BVGGDwu)
curl https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -H "Authorization: Bearer key_test_xxxx"

Respuesta 200 OK

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

Actualizar estado del contracargo

Transiciona un contracargo a un nuevo estado. Úsalo para simular las acciones del operador (ej. marcar un contracargo como ganado o perdido).

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

Parámetros de ruta

ParámetroTipoRequeridoDescripción
charge_idstringSíID del cargo (ej. a1b2c3d4e5f6a7b8c9d0e1f2)
chargeback_idstringSíID del contracargo (ej. chbk_3aaLMNbci2BVGGDwu)

Cuerpo de la petición

CampoTipoRequeridoDescripción
statusstringSíEstado destino. Valores: lost, won, pending_review, under_review, represented, covered
lost_reasonstringNoRequerido solo al transicionar a lost. Motivo por el que se pierde la disputa.
curl -X PATCH https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -H "Authorization: Bearer key_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won"
  }'
curl -X PATCH https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu \
  -H "Authorization: Bearer key_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "lost",
    "lost_reason": "Evidencia insuficiente"
  }'

Respuesta 204 No Content

Sin cuerpo en la respuesta.

Obtener transiciones disponibles

Devuelve la lista de estados a los que puede moverse el contracargo desde su estado actual.

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

Parámetros de ruta

ParámetroTipoRequeridoDescripción
charge_idstringSíID del cargo (ej. a1b2c3d4e5f6a7b8c9d0e1f2)
chargeback_idstringSíID del contracargo (ej. chbk_3aaLMNbci2BVGGDwu)
curl https://api.conekta.io/charges/a1b2c3d4e5f6a7b8c9d0e1f2/chargebacks/chbk_3aaLMNbci2BVGGDwu/transitions \
  -H "Authorization: Bearer key_test_xxxx"

Respuesta 200 OK

[
  { "state_to": "won" },
  { "state_to": "lost" },
  { "state_to": "under_review" }
]

Un arreglo vacío indica que no hay más transiciones disponibles desde el estado actual.

Estados del contracargo

EstadoDescripción
action_requiredContracargo abierto. Se debe enviar evidencia antes de la fecha límite.
pending_reviewEvidencia enviada. En espera de revisión por el banco.
under_reviewEl banco está revisando el caso activamente.
representedEl comercio contra-representó la disputa ante el banco.
wonDisputa resuelta a favor del comercio.
lostDisputa resuelta a favor del tarjetahabiente.
coveredPérdida cubierta bajo un programa de protección.

Errores

CódigoCausa
400Parámetros faltantes o inválidos.
403Llave de producción utilizada, o el cargo no pertenece a tu cuenta.
404Cargo o contracargo no encontrado.
500Error inesperado del servidor.