Skip to main content
Skip table of contents

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"
                }
            ]
        }
    }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.