Chargebacks - Z2Pay Developers

Un chargeback ocurre cuando el titular de la tarjeta disputa un cargo ante el banco emisor. Cuando la adquirente notifica a Z2Pay, abrimos automáticamente un chargeback y movemos el pago a un estado de contestación. Puedes hacer seguimiento del caso, adjuntar pruebas (facturas, comprobantes de entrega, contratos) y descargar los documentos ya enviados.

Los chargebacks no se crean por la API. Se originan a partir de un webhook de la adquirente. A través de la API pública solo puedes consultar casos y gestionar documentos de contestación. Las transiciones de estado (ganado / perdido) son decididas por la adquirente y aplicadas internamente.

Todas las solicitudes utilizan el header x-api-key (consulta Autenticación).

Estados del chargeback

Status	Significado	Qué puedes hacer
`opened`	Chargeback recién creado a partir del webhook de la adquirente.	Esperar — el sistema mueve a `under_review` automáticamente.
`under_review`	En análisis. Ventana abierta para el envío de pruebas.	Enviar documentos de contestación (hasta el plazo `deadlineAt`).
`submitted`	Pruebas enviadas a la adquirente; esperando decisión.	Hacer seguimiento.
`won`	Contestación ganada.	Caso cerrado.
`lost`	Contestación perdida.	Caso cerrado.

Efecto en el pago y en la billetera (wallet):

Al entrar en under_review, el pago asociado queda en contestación (in_protest) y el valor del chargeback es debitado de tu billetera (reserva), junto con la tarifa de chargeback aplicable.
Si el chargeback es won (ganado), el pago vuelve a paid y el valor reservado es reembolsado (acreditado de vuelta), incluyendo la tarifa.
Si el chargeback es lost (perdido), el pago pasa a chargeback y puede aplicarse una multa (penalty) configurable por empresa.

Los movimientos en la billetera aparecen en Billeteras; la configuración de tarifa/multa de chargeback está en Tarifas.

Endpoints

Método	Ruta	Descripción
GET	`/chargebacks`	Lista chargebacks con paginación y filtros.
GET	`/chargebacks/{id}`	Busca un chargeback por ID.
GET	`/chargebacks/transaction/{transactionId}`	Lista chargebacks de una transacción.
GET	`/chargebacks/payment/{paymentId}`	Lista chargebacks de un pago.
GET	`/chargebacks/{id}/documents`	Lista documentos de contestación enviados.
GET	`/chargebacks/{id}/documents/{documentId}/download`	Genera URL firmada para descarga de un documento.
POST	`/chargebacks/{id}/documents`	Envía un documento de contestación.

Listar chargebacks

GET /chargebacks

Retorna los chargebacks de tu empresa con paginación y filtros opcionales. Todos los filtros son query params.

status

string

Filtra por estado. Acepta múltiples valores separados por coma (ej.: opened,under_review). Valores válidos: opened, under_review, submitted, won, lost.

transactionId

string

Filtra los chargebacks de una transacción específica.

paymentId

string

Filtra los chargebacks de un pago específico.

string

Búsqueda textual libre.

startDate

string

Fecha inicial del intervalo, en ISO 8601 con timezone (ej.: 2026-06-01T00:00:00-03:00). El campo de fecha filtrado es definido por dateField.

endDate

string

Fecha final del intervalo, en ISO 8601 con timezone (ej.: 2026-06-30T23:59:59-03:00).

dateField

string

Campo de fecha utilizado por el filtro startDate/endDate. Valores: openedAt o deadlineAt.

sortBy

string

Campo de ordenación. Valores: openedAt, amount, status, deadlineAt.

sortDir

string

Dirección de la ordenación. Valores: asc o desc.

page

integer

predeterminado:"1"

Página (entero positivo).

limit

integer

predeterminado:"10"

Ítems por página (entero positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/chargebacks \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "status=opened,under_review" \
  --data-urlencode "dateField=openedAt" \
  --data-urlencode "startDate=2026-06-01T00:00:00-03:00" \
  --data-urlencode "endDate=2026-06-30T23:59:59-03:00" \
  --data-urlencode "sortBy=openedAt" \
  --data-urlencode "sortDir=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=10"

{
  "data": [
    {
      "id": "cbk_8s2k1d9f0a3b4c5e6f7g",
      "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
      "transactionId": "txn_1a2b3c4d5e6f7g8h9i0j",
      "paymentId": "pay_9z8y7x6w5v4u3t2s1r0q",
      "externalId": "chb_pgmto_abc123",
      "amount": 14990,
      "currency": "BRL",
      "status": "under_review",
      "reasonCode": "4853",
      "reason": "Produto não recebido",
      "deadlineAt": "2026-07-01T23:59:59-03:00",
      "openedAt": "2026-06-24T10:12:00-03:00",
      "resolvedAt": null,
      "createdAt": "2026-06-24T10:12:01-03:00",
      "updatedAt": "2026-06-24T10:12:03-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

data

object[]

Lista de chargebacks de la página.

data[].id

string

ID del chargeback (prefijo cbk_).

data[].transactionId

string

Transacción asociada (prefijo txn_).

data[].paymentId

string

Pago asociado (prefijo pay_).

data[].externalId

string | null

Identificador del chargeback en la adquirente. Puede ser null.

data[].amount

integer

Valor disputado en centavos (ej.: 14990 = R$ 149,90).

data[].currency

string

Moneda del valor. Por defecto BRL.

data[].status

string

Estado actual: opened, under_review, submitted, won o lost.

data[].reasonCode

string | null

Código del motivo informado por la adquirente. Puede ser null.

data[].reason

string | null

Descripción del motivo. Puede ser null.

data[].deadlineAt

string | null

Plazo límite para el envío de pruebas, en ISO 8601. Puede ser null. Después de ese momento, la carga de documentos queda bloqueada.

data[].openedAt

string | null

Cuándo fue abierto el chargeback, en ISO 8601. Puede ser null.

data[].resolvedAt

string | null

Cuándo fue resuelto el caso (ganado/perdido), en ISO 8601. null mientras no esté resuelto.

pagination

object

Metadatos de paginación: page, limit, total y totalPages.

Buscar chargeback por ID

GET /chargebacks/{id}

string

requerido

ID del chargeback (prefijo cbk_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "cbk_8s2k1d9f0a3b4c5e6f7g",
  "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
  "transactionId": "txn_1a2b3c4d5e6f7g8h9i0j",
  "paymentId": "pay_9z8y7x6w5v4u3t2s1r0q",
  "externalId": "chb_pgmto_abc123",
  "amount": 14990,
  "currency": "BRL",
  "status": "under_review",
  "reasonCode": "4853",
  "reason": "Produto não recebido",
  "deadlineAt": "2026-07-01T23:59:59-03:00",
  "openedAt": "2026-06-24T10:12:00-03:00",
  "resolvedAt": null,
  "createdAt": "2026-06-24T10:12:01-03:00",
  "updatedAt": "2026-06-24T10:12:03-03:00"
}

Retorna 404 si el chargeback no existe o no pertenece a tu empresa. Consulta Errores.

Chargebacks de una transacción

GET /chargebacks/transaction/{transactionId}

transactionId

string

requerido

ID de la transacción (prefijo txn_).

page

integer

predeterminado:"1"

Página (entero positivo).

limit

integer

predeterminado:"20"

Ítems por página (entero positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/chargebacks/transaction/txn_1a2b3c4d5e6f7g8h9i0j \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

La respuesta es una lista paginada con el mismo formato de chargeback descrito en Listar chargebacks.

Chargebacks de un pago

GET /chargebacks/payment/{paymentId}

paymentId

string

requerido

ID del pago (prefijo pay_).

page

integer

predeterminado:"1"

Página (entero positivo).

limit

integer

predeterminado:"20"

Ítems por página (entero positivo, máximo 100).

curl -G https://api.sandbox.z2pay.com/chargebacks/payment/pay_9z8y7x6w5v4u3t2s1r0q \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

La respuesta es una lista paginada con el mismo formato de chargeback descrito en Listar chargebacks.

Listar documentos del chargeback

GET /chargebacks/{id}/documents

Retorna los documentos de contestación ya enviados para el chargeback.

string

requerido

ID del chargeback (prefijo cbk_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "cbkd_0a1b2c3d4e5f6g7h8i9j",
      "chargebackId": "cbk_8s2k1d9f0a3b4c5e6f7g",
      "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
      "type": "delivery_proof",
      "contentType": "application/pdf",
      "size": 184320,
      "description": "Comprovante de entrega com assinatura",
      "uploadedBy": "comp_3f9a2b1c8d7e6f5a4b3c",
      "createdAt": "2026-06-24T11:00:00-03:00",
      "updatedAt": "2026-06-24T11:00:00-03:00"
    }
  ]
}

data

object[]

Lista de documentos.

data[].id

string

ID del documento (prefijo cbkd_).

data[].type

string

Tipo del documento: invoice, delivery_proof, signed_contract, screenshot o other.

data[].contentType

string

MIME type detectado: application/pdf, image/jpeg, image/png o image/webp.

data[].size

integer

Tamaño del archivo en bytes.

data[].description

string | null

Descripción informada en el envío. Puede ser null.

data[].uploadedBy

string

Identificador de quien envió el documento.

Retorna 404 si el chargeback no existe o no pertenece a tu empresa.

Descarga de documento

GET /chargebacks/{id}/documents/{documentId}/download

Genera una URL firmada temporal para descargar el archivo. La URL expira en 1 hora.

string

requerido

ID del chargeback (prefijo cbk_).

documentId

string

requerido

ID del documento (prefijo cbkd_).

curl https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents/cbkd_0a1b2c3d4e5f6g7h8i9j/download \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "url": "https://storage.sandbox.z2pay.com/chargebacks/comp_3f9a2b1c8d7e6f5a4b3c/cbk_8s2k1d9f0a3b4c5e6f7g/cbkd_0a1b2c3d4e5f6g7h8i9j.pdf?signature=..."
}

url

string

URL firmada para descarga directa del archivo. Válida por tiempo limitado.

Retorna 404 si el documento no existe o no pertenece a tu empresa.

Carga de documento

POST /chargebacks/{id}/documents

Envía un documento de contestación para el chargeback. Responde con estado 201 y el documento creado.

La carga solo está permitida cuando el chargeback está en under_review y el plazo deadlineAt aún no ha expirado. En cualquier otro caso, la API responde 409.

Este endpoint es idempotente. Envía el header Idempotency-Key con un valor único por solicitud para evitar cargas duplicadas en caso de reintento. Consulta Convenciones.

Parámetros de path

string

requerido

ID del chargeback (prefijo cbk_).

Cuerpo de la solicitud

type

string

requerido

Tipo del documento. Valores: invoice, delivery_proof, signed_contract, screenshot o other.

file

string

requerido

Contenido del archivo en base64. Acepta el prefijo data URI (ej.: data:application/pdf;base64,...) o el base64 puro. Tipos aceptados: PDF, JPEG, PNG y WebP (detectados por el contenido binario, no por la extensión). Tamaño máximo: 10 MB.

description

string

Descripción opcional del documento. Máximo de 500 caracteres. Puede omitirse o enviarse como null.

curl -X POST https://api.sandbox.z2pay.com/chargebacks/cbk_8s2k1d9f0a3b4c5e6f7g/documents \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c2f9a1e-3b4d-4e5f-8a9b-0c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "delivery_proof",
    "description": "Comprovante de entrega com assinatura",
    "file": "data:application/pdf;base64,JVBERi0xLjcKJ..."
  }'

{
  "id": "cbkd_0a1b2c3d4e5f6g7h8i9j",
  "chargebackId": "cbk_8s2k1d9f0a3b4c5e6f7g",
  "companyId": "comp_3f9a2b1c8d7e6f5a4b3c",
  "type": "delivery_proof",
  "contentType": "application/pdf",
  "size": 184320,
  "description": "Comprovante de entrega com assinatura",
  "uploadedBy": "comp_3f9a2b1c8d7e6f5a4b3c",
  "createdAt": "2026-06-24T11:00:00-03:00",
  "updatedAt": "2026-06-24T11:00:00-03:00"
}

Estados y errores

Código	Cuándo ocurre
`201`	Documento enviado con éxito.
`400`	Archivo inválido: vacío, superior a 10 MB o de tipo no aceptado (solo PDF/JPEG/PNG/WebP).
`404`	Chargeback no encontrado.
`409`	Carga no permitida en el estado actual (no está en `under_review`) o plazo expirado.

Formato completo de los errores en Errores.

Pruebas en el Sandbox

Como los chargebacks solo se originan a partir de webhooks de la adquirente, utiliza el simulador del Sandbox para disparar un caso y luego ejercitar la consulta y la carga de documentos.

Crea un pago de prueba

Genera una transacción/pago aprobado siguiendo el Quickstart.

Simula el chargeback

Usa la página Simular eventos para disparar el chargeback sobre el pago creado. El caso entra en under_review automáticamente.

Lista y envía pruebas

Lista el chargeback con GET /chargebacks y envía un documento vía POST /chargebacks/{id}/documents mientras esté en under_review.

Ver también

Pagos

Estados del pago, incluida la contestación.

Billeteras

Débitos, reembolsos y multas generados por los chargebacks.

Tarifas

Configuración de tarifa y multa de chargeback.

Simular eventos

Dispara chargebacks en el entorno de Sandbox.

​Estados del chargeback

​Endpoints

​Listar chargebacks

​Buscar chargeback por ID

​Chargebacks de una transacción

​Chargebacks de un pago

​Listar documentos del chargeback

​Descarga de documento

​Carga de documento

​Parámetros de path

​Cuerpo de la solicitud

​Estados y errores

​Pruebas en el Sandbox

​Ver también

Pagos

Billeteras

Tarifas

Simular eventos

Estados del chargeback

Endpoints

Listar chargebacks

Buscar chargeback por ID

Chargebacks de una transacción

Chargebacks de un pago

Listar documentos del chargeback

Descarga de documento

Carga de documento

Parámetros de path

Cuerpo de la solicitud

Estados y errores

Pruebas en el Sandbox

Ver también