Api de Devoluciones

El API de Devoluciones permite enviar una o mas transacciones en Estado LIQUIDADO a devolver. Solo disponible para los métodos: CARD, YAPE y CUOTEALO.

REQUEST

Path

Method: POST

URL: {{base}}/refund

Headers

Campo

Descripcion

Valor Aceptado

Tipo

Authorization

Token de identificación para uso del API creado previamente en API de Seguridad

Bearer <Access Token>

String

ALG-API-VERSION

Versión del API a usar

Cadena alfanumérica:

1709847567

String

payment-facilitator-code

Identificador del PF - uso obligatorio para PF

Cadena alfanumérica

String

Body

Campo	Descripcion	Valor Aceptado	Tipo	Obligatorio
`merchant_code`	Identificador del comercio	Cadena Alfanumérica	`String`	SI
`operations`	Array que contiene Objetos de transacciones a devolver		`Array`	SI
`operations.[].type`	Tipo de devolución	TOTAL PARTIAL	`String`	SI
`operations.[].merchant_operation_number`	Número de pedido de la operación	Cadena numérica mayor o igual de 6 dígitos	`String`	SI
`operations.[].transaction_id`	Código alfanumérico de la transacción		`String`	NO
`operations.[].refund_amount`	Monto a devolver en centavos. La separación de decimales se aplicará según la moneda. Ej.: Para S/. 10.50, se debe enviar “1050”		`String`	SI
`payment_details.additional_fields`	Diccionario para enviar campos y valores personalizados como `key:value` Ej.: external_id:21871054	`key:value`	`Dictionary`	NO

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

RESPONSE

Campo	Descripcion	Valor Aceptado	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	Cadena Alfanumérica	`String`	SI
`operations`	Array que contiene Objetos de transacciones a devolver		`Array`	SI
`operations.[].refund_id`	UUID único de la devolución		`String`	SI
`operations.[].state`	Estado de la solicitud	REGISTERED REJECTED	`String`	SI
`operations.[].refund_reason`	Motivo o detalle asociado al estado		`String`	SI
`operations.[].merchant_operation_number`	Número de pedido de la operación	Cadena numérica mayor o igual de 6 dígitos	`String`	SI
`operations.[].type`	Tipo de devolución	TOTAL PARTIAL	`String`	SI
`operations.[].merchant_operation_number`	Número de pedido de la operación	Cadena numérica mayor o igual de 6 dígitos	`String`	SI
`operations.[].transaction_id`	Código alfanumérico de la transacción		`String`	SI
`operations.[].refund_amount`	Monto a devolver en centavos		`String`	SI
`operations.[].transaction_amount`	Monto original de la transacción en centavos		`String`	SI
`operations.[].currency`	Código ISO 4217 de la moneda de la transacción.	Cadena numérica	`String`	SI
`operations.[].additional_fields`	Diccionario para enviar campos y valores personalizados como `key:value` Ej.: external_id:21871054	`key:value`	`Dictionary`	NO
`operations.[].payment_method`	Objeto relacionado al medio y procesador de pago		`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		`String`	SI
`operations.[].lifecycle`	Array que contiene listado de los estado por la cual pasó la transacción		`Array`	SI
`operations.[].lifecycle.[].state`	Estado de la transacción	REGISTERED REJECTED	`String`	SI
`operations.[].lifecycle.[].date`	Objeto que contiene la fecha en la que se realizó el cambio de estado		`Object`	SI
`operation.[].lifecycle.[].date.utc_time`	Fecha en UTC	Cadena alfanumérica	`String`	SI
`operation.[].lifecycle.[].date.unix_time`	Fecha en unix time	Cadena alfanumérica	`Integer`	SI
`meta.status`	Objeto que contiene el resultado del flujo ejecutado		`Object`	SI
`meta.status.code`	Código que representa el resultado del flujo ejecutado	Cadena numérica	`String`	SI
`meta.status.message_ilgn`	Objeto que contiene el mensaje resultante del flujo		`Object`	SI
`meta.status.message_ilgn.[].locale`	Localidad a nivel de lenguaje para el mensaje del flujo ejecutado	Cadena alfanumérica	`String`	SI
`meta.status.message_ilgn.[].value`	Mensaje resultante del flujo ejecutado	Cadena alfanumérica	`String`	SI

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.788
                    }
                }
            ]
        }
    ],
    "meta": {
        "status": {
            "code": "00",
            "message_ilgn": [
                {
                    "locale": "es_PE",
                    "value": "Se procesó correctamente la petición"
                }
            ]
        }
    }
}