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": "transaction",
        "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:

- transaction

- 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]