Introducción a la API de Reembolsos

La API de Reembolsos de Clip te permite realizar un reembolso total o parcial de cualquier transacción que haya sido completada con tarjeta.

Sólo tienes que solicitar a la API el reembolso de un pago y recibirás el estado del reembolso (Aprobado, Declinado). Cuando el reembolso es aprobado, los fondos son reembolsados a la tarjeta de crédito o débito con la que se completó el pago.

Además del pago, el reembolso es un tipo de transacción. Por lo tanto, cada vez que solicitas un reembolso a través de la API, se genera un nuevo número de identificación (id) y de recibo (receipt_no) específicos para ese reembolso. Sin embargo, si solicitas un reembolso dentro de las primeras 24 h después de haber completado el pago, el reembolso se identifica con el mismo id de la transacción original ya que en este caso es una cancelación.

¿Qué puedo hacer con la API de Reembolsos?

Puedes solicitar el reembolso total o parcial de cualquier pago que haya sido completado con tarjeta dentro de un plazo no mayor a 180 días naturales. La API también te permite consultar información detallada de los reembolsos que has realizado.

¿Qué necesito para hacer una solicitud de reembolso?

Estos son los requerimientos para hacer solicitudes a la API de Reembolsos:

Una cuenta Clip activa.
Un token de autenticación.
Un balance^* igual o mayor al monto que vas a reembolsar.
Que el tiempo transcurrido entre la compleción de la transacción y la solicitud del reembolso no sea mayor a 180 días naturales.

Balance

^* El balance es la cantidad de ventas que has realizado en el día en que solicitas el reembolso (y que no ha sido depositado en tu cuenta) menos la cantidad total de dinero que has reembolsado en ése mismo día. Balance actual = ventas totales - reembolsos totales. Para conocer tu balance deberás consultar las ventas del día en la sección Transacciones del panel de Clip y llevar un registro de tus reembolsos.

¿Cuál es la URL base?

Para hacer llamadas a la API, debes utilizar la siguiente URL base:

https://api.payclip.com

¿Cuáles son los endpoints de la API de Reembolsos?

La API de Checkout tiene dos endpoints:

POST /refunds

Solicitar el reembolso de una transacción.

GET /refunds/{id}

Consultar la información de un reembolso.

¿Cuáles son los parámetros del encabezado?

Elemento	Descripción	Tipo	Requerido/opcional	Notas
Content-type	Define el formato del objeto de solicitud.	application/json	Requerido	Solicitud en formato JSON.
idempotency-key^†	Valor único que puedes generar y utilizar para identificar subsecuentes intentos de reembolso de una misma transacción.	String	Opcional	Tiene duración de 1 minuto.
Authorization	Especifica el token de acceso.	String	Requerido	< api_token >

^† El parámetro idempotency-key sólo puede ser enviado en la solicitud al endpoint POST Solicitar el reembolso de una transacción.

¿Cuál es el objeto JSON de reembolso?

El siguiente es un ejemplo de objeto JSON de reembolso.

{
    "id": "7f2ffd14-a171-487f-acb3-ede3b19a5a6e",
    "status": "approved",
    "status_message": "Refunded. Merchant initiated.",
    "amount": 0.01,
    "receipt_no": "9vcLT53",
    "created_at": "2023-08-15T18:09:13Z",
    "currency": "MXN",
    "reference": {
        "type": "payment",
        "id": "b0e3bd81-d3db-41a2-ab8b-e56ccbd32f11"
    },
    "reason": "reason"
}

¿Cuál es el esquema del objeto de reembolso?

A continuación se enlistan y describen los elementos del objeto de reembolso.

Elemento		Descripción	Tipo	Notas
id^‡		Número de identificación del reembolso.	String	Formato UUID.
status		Estado de la solicitud del reembolso.	String	Puede ser: - approved - declined
status_message		Mensaje con detalles del estado de la solicitud.	String
amount		Cantidad reembolsada.	Float	Debe ser igual al monto de la transacción original (versión beta).
receipt_no		Número de recibo del reembolso.	String	Se mostrará en el evoucher de la transacción.
created_at		Fecha de creación del reembolso.	String	Formato ISO 8601 (YYYY-MM-DDTHH-MM-SSZ)
currency		Código de tres letras que identifica el tipo de moneda de la transacción.	String	Sólo acepta MXN (pesos mexicanos).
reference		Objeto que detalla el número y tipo de referencia de la transacción original reembolsada.	Objeto
	type	Tipo de identificación con el que se hace referencia a la transacción original.	String	Puede ser: - payment - receipt
	id	Número de identificación de la transacción original reembolsada.	String	Formato: UUID.
reason		Motivo del reembolso.	String

^‡ Este número de identificación del reembolso, id, es generado en la respuesta del endpoint POST Solicitar el reembolso de una transacción, mismo que deberás utilizar en el path parameter de la solicitud GET Consultar la información de un reembolso.

¿Cuáles son los códigos de error?

La siguiente tabla contiene una lista y la descripción de algunos mensajes de error y su asociación con estados HTTP.

Código HTTP	Código de error	Mensaje
400	CL2200	Unable to process the request. Required fields are missing.
403	CL1500	Unauthorized
404	AI1300	Transaction ID not found.
	CL301	Payment not found.
	AI1800	The payment is not approved.
409	AI1801	The refund amount is greater than the original.
	AI1802	The refund amount, plus previous refunds, is greater than the original amount.
	AI1803	The refund date has expired.
	AI1804	Refund declined.The original transaction is in dispute ^#.
	AI1805	Refunds are disabled.
	AI1806	Refund is disabled for payments with MSI and MCI
	AI1400	Insufficient funds to make the refund.
	AI1807	Refund in process for this transaction. Please try again later.
500	AI1899	Internal error.

^# El reembolso es declinado debido a que la transacción original se encuentra en disputa.

Ejemplo del objeto JSON de error

{
"error_code": "AI1801",
"message": "Conflict",
"detail": [
  "The refund amount is greater that the original"
  ]
}

📘
¿Necesitas Ayuda?
Consulta las nuestro centro de soporte a desarrolladores y el centro de ayuda Clip.
Si lo que buscas no está documentado, contáctanos por alguno de los siguientes medios:

Activa el botón de Ayuda y llena el formulario. No olvides proporcionar un correo electrónico y tus dudas para que podamos asistirte de manera eficiente.

Publica tu pregunta en nuestro Foro. Publicar en el foro puede ayudar a otros desarrolladores que están experimentando el mismo problema.

Envía un correo electrónico a la dirección [email protected].

O comunícate con nuestra área de Customer Happiness:

Llámanos al 55 6393-2323, Clip es el único con atención personalizada 24/7 los 365 días del año.

Envíanos un mensaje por WhatsApp al 55 6393-2323.

Escríbenos al correo [email protected]