Refunds (Reembolsos) - Z2Pay Developers

Un refund (reembolso/contracargo) devuelve al cliente el valor de un pago ya liquidado. En Z2Pay, un refund se origina a partir de un pago (pay_...) y atraviesa un ciclo de estados hasta ser procesado en el gateway o mediante transferencia (en el caso de boleto). Esta página cubre los endpoints de consulta y decisión manual de refunds: buscar por ID, listar por transacción o por pago, y aprobar o rechazar un refund pendiente.

La creación de un refund no se realiza aquí. Para abrir una solicitud de reembolso, utiliza el endpoint de contracargo en Payments (POST /transactions/{transactionId}/payments/{paymentId}/refund). Esta página documenta lo que ocurre después de que el refund ya existe.

Todas las solicitudes utilizan el header x-api-key. Consulta Autenticación.

Endpoints

Método	Ruta	Descripción
`GET`	`/refunds/{id}`	Obtiene un refund por ID
`GET`	`/refunds/transaction/{transactionId}`	Lista los refunds de una transacción
`GET`	`/refunds/payment/{paymentId}`	Lista los refunds de un pago
`POST`	`/refunds/{id}/approve`	Aprueba un refund pendiente y lo envía a procesamiento
`POST`	`/refunds/{id}/refuse`	Rechaza un refund pendiente

Estados del refund

El campo status indica en qué punto del ciclo se encuentra el refund. Los estados terminales (que no cambian) son refunded, refused y failed.

Status	Significado
`pending`	Esperando decisión manual (aprobar o rechazar)
`approved`	Aprobado; en transición hacia el procesamiento
`processing`	En proceso en el gateway
`refunded`	Reembolso completado (terminal)
`refused`	Solicitud rechazada (terminal)
`failed`	Error en el procesamiento (terminal)
`awaiting_bank_details`	Boleto: esperando que el cliente informe los datos bancarios
`bank_details_received`	Boleto: datos bancarios recibidos, listo para la transferencia
`invalid_bank_details`	Boleto: datos bancarios inválidos; nueva solicitud de datos enviada
`ted_processing`	Boleto: transferencia (PIX/TED) en procesamiento

Auto-approve de la company. Cada empresa tiene una configuración de aprobación automática de reembolsos (habilitada por defecto). Con auto-approve activado, un refund de tarjeta se crea, aprueba y procesa de inmediato — es decir, puede nacer directamente en approved/processing y nunca pasar por pending. Con auto-approve desactivado, el refund nace en pending y debe ser aprobado mediante los endpoints que se describen a continuación.

Flujo de boleto. El boleto no se contracarga en el gateway: el valor se devuelve mediante transferencia bancaria (PIX/TED), por lo que es necesario recopilar los datos bancarios del cliente. Por eso, un refund de boleto, al ser aprobado, pasa a awaiting_bank_details en lugar de processing. Una vez que los datos llegan (bank_details_received), la transferencia se procesa (ted_processing) hasta completarse (refunded). La recopilación de datos bancarios ocurre a través de un enlace/invitación enviado al cliente, fuera de este conjunto de endpoints.

Buscar refund por ID

GET /refunds/{id}

Devuelve los datos completos de un refund.

string

requerido

ID del refund (prefijo ref_).

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

{
  "id": "ref_3kf9d2a7b1c5e8",
  "companyId": "comp_a1b2c3d4e5",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refunded",
  "reason": "Cliente solicitou cancelamento",
  "requestedBy": "api",
  "requestedByType": "api",
  "paymentMethod": "credit_card",
  "failureReason": null,
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:45:02.000Z",
  "refundedAt": "2026-06-24T13:45:05.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:45:05.000Z",
  "deletedAt": null
}

string

ID del refund (ref_...).

transactionId

string

ID de la transacción (txn_...).

paymentId

string

ID del pago contracargado (pay_...).

amount

integer

Valor reembolsado, en centavos (ej.: 4990 = R$ 49,90).

currency

string

Moneda. Siempre BRL.

status

string

Estado actual del refund (ver tabla de estados arriba).

reason

string

Motivo informado en la creación del refund.

requestedBy

string

Identificador de quien solicitó el refund.

requestedByType

string

Origen de la solicitud: api, admin, customer o gateway.

paymentMethod

string | null

Método del pago contracargado (ej.: credit_card, boleto). Puede ser null.

failureReason

string | null

Motivo del error cuando status es failed. En caso contrario, null.

reviewedBy

string | null

Quién aprobó/rechazó el refund. null mientras no haya sido revisado.

reviewedAt

string | null

Fecha/hora de la revisión (ISO 8601). null mientras no haya sido revisado.

refundedAt

string | null

Fecha/hora de la conclusión del reembolso (ISO 8601). null mientras no haya concluido.

createdAt

string

Fecha/hora de creación (ISO 8601).

updatedAt

string

Fecha/hora de la última actualización (ISO 8601).

deletedAt

string | null

Fecha/hora de eliminación lógica. Normalmente null.

Errores

Status	Cuándo ocurre
`404`	Refund no encontrado

Consulta Errores para ver el formato de la respuesta de error.

Listar refunds de una transacción

GET /refunds/transaction/{transactionId}

Devuelve, de forma paginada, todos los refunds asociados a una transacción.

transactionId

string

requerido

ID de la transacción (prefijo txn_).

page

integer

predeterminado:"1"

Página (comienza en 1).

limit

integer

predeterminado:"20"

Ítems por página. Mínimo 1, máximo 100.

curl "https://api.sandbox.z2pay.com/refunds/transaction/txn_9z8y7x6w5v4u?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "ref_3kf9d2a7b1c5e8",
      "transactionId": "txn_9z8y7x6w5v4u",
      "paymentId": "pay_1a2b3c4d5e6f",
      "amount": 4990,
      "currency": "BRL",
      "status": "refunded",
      "reason": "Cliente solicitou cancelamento",
      "paymentMethod": "credit_card",
      "refundedAt": "2026-06-24T13:45:05.000Z",
      "createdAt": "2026-06-24T13:44:58.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

data

array

Lista de refunds (misma estructura que Buscar refund por ID).

pagination

object

Mostrar campos

page

integer

Página actual.

limit

integer

Ítems por página.

total

integer

Total de refunds encontrados.

totalPages

integer

Total de páginas.

Listar refunds de un pago

GET /refunds/payment/{paymentId}

Igual al endpoint anterior, pero filtra por los refunds de un pago específico.

paymentId

string

requerido

ID del pago (prefijo pay_).

page

integer

predeterminado:"1"

Página (comienza en 1).

limit

integer

predeterminado:"20"

Ítems por página. Mínimo 1, máximo 100.

curl "https://api.sandbox.z2pay.com/refunds/payment/pay_1a2b3c4d5e6f?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

La respuesta tiene el mismo formato (data + pagination) que el endpoint por transacción.

Aprobar refund

POST /refunds/{id}/approve

Aprueba un refund que está pendiente y lo envía a procesamiento. Para tarjeta, el refund pasa al gateway. Para boleto, el refund queda a la espera de los datos bancarios del cliente (awaiting_bank_details).

string

requerido

ID del refund (prefijo ref_).

Este endpoint es idempotente: reenviar la misma solicitud con el header Idempotency-Key no genera un efecto duplicado. Consulta Convenciones.

Idempotency-Key

string

Clave única para garantizar que la aprobación no se aplique más de una vez.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/approve \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c1f0e2a-9b3d-4a6e-8f12-5d0c9b8a7e6f"

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "processing",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:50:11.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:50:11.000Z"
}

El status retornado depende del método de pago: tarjeta suele pasar a processing (y luego a refunded), mientras que boleto pasa a awaiting_bank_details.

Errores

Status	Cuándo ocurre
`404`	Refund no encontrado
`409`	El refund no puede aprobarse en el estado actual (ej.: ya es terminal)

Consulta Errores para ver el formato de la respuesta.

Rechazar refund

POST /refunds/{id}/refuse

Rechaza un refund pendiente, llevándolo al estado terminal refused.

string

requerido

ID del refund (prefijo ref_).

El cuerpo es opcional y acepta un único campo:

reason

string

Motivo del rechazo. Cuando se envía, debe tener entre 1 y 4000 caracteres. El campo es validado, pero no reemplaza el reason original del refund en la respuesta (que conserva el motivo informado en la creación).

Este endpoint es idempotente — incluye el header Idempotency-Key para reenvíos seguros.

Idempotency-Key

string

Clave única para garantizar que el rechazo no se aplique más de una vez.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/refuse \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 1b2c3d4e-5f60-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Reembolso fora do prazo de política" }'

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refused",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:52:40.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:52:40.000Z"
}

Errores

Status	Cuándo ocurre
`404`	Refund no encontrado
`409`	El refund no puede rechazarse en el estado actual (ej.: ya es terminal)

Consulta Errores para ver el formato de la respuesta.

Ver también

Payments

Crea un refund contracargando un pago.

Transactions

Comprende la transacción que originó el pago.

Chargebacks

Contracargos iniciados por el emisor de la tarjeta.

Errores

Formato de los errores y cómo gestionarlos.

​Endpoints

​Estados del refund

​Buscar refund por ID

​Listar refunds de una transacción

​Listar refunds de un pago

​Aprobar refund

​Rechazar refund

​Ver también

Payments

Transactions

Chargebacks

Errores

Endpoints

Estados del refund

Buscar refund por ID

Listar refunds de una transacción

Listar refunds de un pago

Aprobar refund

Rechazar refund

Ver también