API de Devoluciones

El API de Devoluciones permite enviar una o más transacciones en estado LIQUIDADO a devolver. Solo está disponible para los métodos CARD, YAPE y CUOTEALO.

POST /refund

endpoint

Pre-Producción

https://api.preprod.alignet.io/refund

Producción

https://api.alignet.io/refund

La devolución se procesa después del estado AUTORIZADO, cuando la transacción ya se encuentra en LIQUIDADO. Si la operación aún no fue liquidada, el mecanismo correcto es el extorno, no la devolución.

Request

Headers

Campo	Descripción	Valor	Tipo	Obligatorio
`Authorization`	Token de identificación para uso del API creado previamente en API de Seguridad	`Bearer <Access Token>`	String	SI
`ALG-API-VERSION`	Versión del API a usar	`1709847567`	String	SI
`payment-facilitator-code`	Identificador del PF, obligatorio para Payment Facilitator	Cadena alfanumérica	String	NO

Body

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`merchant_code`	Identificador del comercio	`41bb301e-3c37-4332-accb-ed5ec19081e4`	String	SI
`operations`	Array que contiene objetos de transacciones a devolver	Array	Array	SI
`operations[].type`	Tipo de devolución	`TOTAL`, `PARTIAL`	String	SI
`operations[].merchant_operation_number`	Número de pedido de la operación	`239766`	String	SI
`operations[].transaction_id`	Código alfanumérico de la transacción	`bko66gpi8czns4tcde93q96vd`	String	NO
`operations[].refund_amount`	Monto a devolver en centavos	`1050`	String	SI
`operations[].additional_fields`	Diccionario para enviar campos y valores personalizados como `key:value`	`external_id:21871054`	Dictionary	NO

Para S/. 10.50 debes enviar 1050. La separación de decimales se aplica según la moneda.

Ejemplo (JSON)

{
  "merchant_code": "41bb301e-3c37-4332-accb-ed5ec19081e4",
  "operations": [
    {
      "type": "TOTAL",
      "merchant_operation_number": "239766",
      "transaction_id": null,
      "refund_amount": "1050",
      "additional_fields": {
        "canal": "WEB",
        "reason": "cliente no reconoció el consumo",
        "description": "solicitud por desconocimiento"
      }
    }
  ]
}

Siguiente paso

Consulta Unitaria de Devolución

Consulta una solicitud puntual usando merchant_code y merchant_operation_number.

Consulta Masiva de Devolución

Lista devoluciones por rango de fechas y filtros operativos.

Response

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`success`	Indica si el proceso se realizó correctamente	`true`, `false`	String	SI
`action`	Acción ejecutada	`refund`	String	SI
`merchant_code`	Identificador del comercio	`41bb301e-3c37-4332-accb-ed5ec19081e4`	String	SI
`operations`	Array que contiene objetos de transacciones a devolver	Array	Array	SI
`operations[].refund_id`	UUID único de la devolución	UUID	String	SI
`operations[].state`	Estado de la solicitud	`REGISTERED`, `REJECTED`	String	SI
`operations[].refund_reason`	Motivo o detalle asociado al estado	`Solicitud recibida y validada`	String	SI
`operations[].type`	Tipo de devolución	`TOTAL`, `PARTIAL`	String	SI
`operations[].merchant_operation_number`	Número de pedido de la operación	`239766`	String	SI
`operations[].transaction_id`	Código alfanumérico de la transacción	`bko66gpi8czns4tcde93q96vd`	String	SI
`operations[].refund_amount`	Monto a devolver en centavos	`1050`	String	SI
`operations[].transaction_amount`	Monto original de la transacción en centavos	`1050`	String	SI
`operations[].currency`	Código ISO 4217 de la moneda de la transacción	`604`	String	SI
`operations[].additional_fields`	Diccionario con campos personalizados enviados en el request	Dictionary	Dictionary	NO
`operations[].payment_method`	Objeto relacionado al medio y procesador de pago	Object	Object	SI
`operations[].payment_method.name`	Nombre del método de pago	`CARD`, `YAPE`, `CUOTEALO`	String	SI
`operations[].payment_method.brand`	Marca de la tarjeta	`VISA`, `MSCD`, `AMEX`, `DINC`	String	SI
`operations[].payment_method.masked_pan`	Tarjeta enmascarada	`447411******2240`	String	SI
`operations[].lifecycle`	Array con el listado de estados por los que pasó la devolución	Array	Array	SI
`operations[].lifecycle[].state`	Estado de la devolución	`REGISTERED`, `REJECTED`	String	SI
`operations[].lifecycle[].date`	Objeto con la fecha del cambio de estado	Object	Object	SI
`operations[].lifecycle[].date.utc_time`	Fecha en UTC	`2025-05-26T06:06:45`	String	SI
`operations[].lifecycle[].date.unix_time`	Fecha en unix time	`1748239605`	Integer	SI
`meta.status`	Objeto que contiene el resultado del flujo ejecutado	Object	Object	SI
`meta.status.code`	Código que representa el resultado del flujo ejecutado	`00`	String	SI
`meta.status.message_ilgn`	Objeto que contiene el mensaje resultante del flujo	Object	Object	SI
`meta.status.message_ilgn[].locale`	Localidad a nivel de lenguaje para el mensaje del flujo ejecutado	`es_PE`	String	SI
`meta.status.message_ilgn[].value`	Mensaje resultante del flujo ejecutado	`Se procesó correctamente la petición`	String	SI

Ejemplo (JSON)

{
  "success": "true",
  "action": "refund",
  "merchant_code": "41bb301e-3c37-4332-accb-ed5ec19081e4",
  "operations": [
    {
      "refund_id": "922178aa-ce4c-4c5f-8190-82fa7e009425",
      "state": "REGISTERED",
      "refund_reason": "Solicitud recibida y validada",
      "type": "TOTAL",
      "merchant_operation_number": "239766",
      "transaction_id": "bko66gpi8czns4tcde93q96vd",
      "refund_amount": "1050",
      "transaction_amount": "1050",
      "currency": "604",
      "payment_method": {
        "name": "CARD",
        "brand": "VISA",
        "masked_pan": "447411******2240"
      },
      "additional_fields": {
        "canal": "WEB",
        "reason": "cliente no reconoció el consumo",
        "description": "solicitud por desconocimiento"
      },
      "lifecycle": [
        {
          "state": "REGISTERED",
          "date": {
            "utc_time": "2025-05-26T06:06:45",
            "unix_time": 1748239605
          }
        }
      ]
    }
  ],
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Se procesó correctamente la petición"
        }
      ]
    }
  }
}

Primeros pasos

Integración

Pagos

Gestión y Operaciones

Pre-Producción

Producción

Request

Headers

Body

Ejemplo (JSON)

Siguiente paso

Consulta Unitaria de Devolución

Consulta Masiva de Devolución

Response

Ejemplo (JSON)

Pre-Producción

Producción

​Request

​Headers

​Body

​Ejemplo (JSON)

​Siguiente paso

Consulta Unitaria de Devolución

Consulta Masiva de Devolución

​Response

​Ejemplo (JSON)

Request

Headers

Body

Ejemplo (JSON)

Siguiente paso

Response

Ejemplo (JSON)