> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay-me.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API de Devoluciones
> Envía solicitudes de devolución total o parcial sobre transacciones liquidadas.
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`.
[https://api.preprod.alignet.io/refund](https://api.preprod.alignet.io/refund)
[https://api.alignet.io/refund](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 ` | 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)
```json theme={"system"}
{
"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 una solicitud puntual usando `merchant_code` y `merchant_operation_number`.
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)
```json theme={"system"}
{
"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"
}
]
}
}
}
```