API de Cancelación

El API de Cancelación permite cancelar una transacción generada previamente por el API de Autorización para ecommerce. Con el método DELETE del orquestador, las transacciones se pueden cancelar o extornar según el estado en el que se encuentren.

DELETE /charges/{merchant_code}/{merchant_operation_number}

endpoint

Pre-Producción

https://api.preprod.alignet.io/charges/{merchant_code}/{merchant_operation_number}

Producción

https://api.alignet.io/charges/{merchant_code}/{merchant_operation_number}

Este endpoint cambia el estado de la operación según el estado actual de la transacción y el método de pago. Si necesitas confirmar el resultado final luego del cambio, apóyate también en Consulta y Notificaciones.

¿Qué cubre esta sección?

Cancelación

Las transacciones en estado REGISTRADO o PENDIENTE pasan a estado CANCELADO para CARD cuando usa Redirect, CUOTEALO, QR, BANK_TRANSFER y PAGOEFECTIVO.

Extorno

Las transacciones en estado AUTORIZADO pasan a estado EXTORNADO para CARD y YAPE.

Validación backend

Usa este endpoint para cerrar correctamente una operación desde backend cuando el negocio requiera anular o revertir el cobro.

Manejo por estado

El comportamiento no es igual para todos los métodos. La transición depende del estado actual de la transacción.

Request

Antes de consumir este endpoint, solicita tu Access Token en Autenticación.

Path

DELETE {{base}}/charges/{merchant_code}/{merchant_operation_number}

Campo	Descripción	Formato	Tipo
`merchant_code`	Identificador del comercio.	Cadena alfanumérica	String
`merchant_operation_number`	Número de operación.	Cadena alfanumérica	String

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. Uso obligatorio para PF.	Cadena alfanumérica	String	NO

Authorization: Bearer {access_token}
ALG-API-VERSION: 1709847567
payment-facilitator-code: {pf_code}

Response

Se devuelve la misma estructura general que el API de Consulta, con las transacciones que se pudieron cancelar o extornar de forma exitosa.

Operación

Campo	Descripción	Tipo	Obligatorio
`success`	Indica si el proceso se realizó correctamente. Valores esperados: `true` o `false`.	Boolean	SI
`merchant_code`	Identificador del comercio.	String	SI
`merchant_operation_number`	Número de pedido de la operación cancelada o extornada. Puede estar presente a nivel raíz según la integración.	String	NO
`operation`	Visible cuando se encontró el `merchant_operation_number`. Objeto con el detalle de la operación.	Object	SI
`operation.merchant_operation_number`	Número de pedido de la operación cancelada o extornada.	String	SI
`operation.amount`	Monto de la operación.	String	SI
`operation.currency`	Código de moneda de la operación.	String	SI
`operation.state`	Visible cuando la operación se pudo cancelar o extornar. Estado al cual cambió la operación. Valores frecuentes: `CANCELADO`, `EXTORNADO`.	String	SI
`operation.transactions`	Lista de transacciones canceladas o extornadas sobre la operación. Este objeto cambia según el método de pago: Tarjeta, Transferencia Bancaria, QR, Yape, Cuotéalo, PagoEfectivo.	Array	SI

Transacciones

Campo	Descripción	Tipo	Obligatorio
`operation.transactions[].transaction_id`	Identificador único de la transacción afectada.	String	SI
`operation.transactions[].channel`	Canal de la transacción. Valor esperado: `ecommerce`.	String	SI
`operation.transactions[].state`	Estado final de la transacción luego del cambio. Valores frecuentes: `CANCELADO`, `EXTORNADO`.	String	SI
`operation.transactions[].state_reason`	Observación o motivo del cambio de estado.	String	SI
`operation.transactions[].amount`	Monto de la transacción.	String	SI
`operation.transactions[].currency`	Código de la moneda de la transacción.	String	SI
`operation.transactions[].payment_method`	Objeto con información del método de pago usado.	Object	SI
`operation.transactions[].continue_url`	Puede aparecer si el flujo original generó URL de continuación.	String	NO
`operation.transactions[].expiration_date`	Puede aparecer si el flujo original incluía expiración.	Object	NO
`operation.transactions[].processor_response`	Resultado devuelto por la procesadora. En extornos puede incluir datos específicos como `reverse_date` o `reverse_code`.	Object	NO
`operation.transactions[].authentication_result`	Resultado de autenticación asociado a la transacción, cuando aplique.	Object	NO
`operation.transactions[].risk_evaluation`	Resultado de evaluación antifraude, cuando aplique.	Object	NO
`operation.transactions[].additional_fields`	Datos adicionales enviados en la autorización.	Object	NO
`operation.transactions[].lifecycle`	Historial de estados por los que pasó la transacción.	Array	SI

Campo	Descripción	Tipo	Obligatorio
`meta`	Objeto que contiene metadatos del flujo ejecutado.	Object	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.	String	SI
`meta.status.message_ilgn`	Lista de mensajes resultantes del flujo.	Array	SI
`meta.status.message_ilgn[].locale`	Localidad a nivel de lenguaje para el mensaje del flujo ejecutado.	String	SI
`meta.status.message_ilgn[].value`	Mensaje resultante del flujo ejecutado.	String	SI

Ejemplo: cancelación exitosa

{
  "success": true,
  "merchant_code": "abc",
  "merchant_operation_number": "2836824",
  "operation": {
    "merchant_operation_number": "2836824",
    "amount": "1000",
    "currency": "604",
    "created_at": {
      "utc_time": "2024-07-05T16:46:12",
      "unix_time": 1720197972
    },
    "state": "CANCELADO",
    "transactions": [
      {
        "transaction_id": "9namjcnjvqzas2t33xyfrqr2h",
        "channel": "ecommerce",
        "state": "CANCELADO",
        "state_reason": "Usuario cancelo el metodo de pago",
        "amount": "1000",
        "currency": "604",
        "additional_fields": null,
        "payment_method": {
          "method_name": "PAGOEFECTIVO",
          "method_details": {
            "callback_url": "https://jjap9ekgee.execute-api.us-east-1.amazonaws.com/development/redirect/prueba/merchant_notification_response"
          }
        },
        "expiration_date": null,
        "processor_response": null,
        "lifecycle": [
          {
            "state": "REGISTRADO",
            "date": {
              "utc_time": "2024-07-05T16:46:12",
              "unix_time": 1720197972
            }
          },
          {
            "state": "PENDIENTE",
            "date": {
              "utc_time": "2024-07-05T16:46:13",
              "unix_time": 1720197973
            }
          },
          {
            "state": "CANCELADO",
            "date": {
              "utc_time": "2024-07-05T16:47:22",
              "unix_time": 1720198042
            }
          }
        ]
      }
    ]
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Se proceso correctamente la peticion"
        }
      ]
    }
  }
}

Ejemplo: extorno exitoso

{
  "success": true,
  "merchant_code": "abc",
  "merchant_operation_number": "8522366",
  "operation": {
    "merchant_operation_number": "8522366",
    "amount": "150",
    "currency": "604",
    "created_at": {
      "utc_time": "2024-07-05T20:34:18",
      "unix_time": 1720211658
    },
    "state": "EXTORNADO",
    "transactions": [
      {
        "transaction_id": "0fuwnd6miwsomisn0ikqivav9",
        "channel": "ecommerce",
        "state": "EXTORNADO",
        "state_reason": "Pago anulado",
        "amount": "150",
        "currency": "604",
        "additional_fields": null,
        "payment_method": {
          "method_name": "CARD",
          "method_details": {
            "redirect_url": null,
            "callback_url": null,
            "masked_pan": "545545******3401",
            "brand": "MASTERCARD",
            "bin": "545545",
            "last_pan": "3401",
            "card_type": "CIRRUS",
            "card_country": "PE",
            "issuer": "SCOTIABANK PERU S.A.A."
          }
        },
        "continue_url": null,
        "expiration_date": null,
        "risk_evaluation": null,
        "authentication_result": null,
        "processor_response": {
          "reverse_date": "05-07-2024 20:34:19",
          "reverse_code": "T90261",
          "brand_transaction_id": "0705203422939657",
          "result_message": {
            "code": "00",
            "description": "Aprobado"
          }
        },
        "lifecycle": [
          {
            "state": "REGISTRADO",
            "date": {
              "utc_time": "2024-07-05T20:34:18",
              "unix_time": 1720211658
            }
          },
          {
            "state": "PENDIENTE",
            "date": {
              "utc_time": "2024-07-05T20:34:19",
              "unix_time": 1720211659
            }
          },
          {
            "state": "AUTORIZADO",
            "date": {
              "utc_time": "2024-07-05T20:34:24",
              "unix_time": 1720211664
            }
          },
          {
            "state": "EXTORNADO",
            "date": {
              "utc_time": "2024-07-05T21:34:24",
              "unix_time": 1720211664
            }
          }
        ]
      }
    ]
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Se proceso correctamente la peticion"
        }
      ]
    }
  }
}

Siguiente paso

API de Consulta

Confirma el estado final de la operación y revisa el detalle por método cuando lo necesites.

Notificaciones

Complementa la cancelación con notificaciones S2S para trazabilidad operativa.

Primeros pasos

Integración

Pagos

Gestión y Operaciones

Pre-Producción

Producción

¿Qué cubre esta sección?

Cancelación

Extorno

Validación backend

Manejo por estado

Request

Path

Headers

Response

Ejemplo: cancelación exitosa

Ejemplo: extorno exitoso

Siguiente paso

API de Consulta

Notificaciones

Pre-Producción

Producción

​¿Qué cubre esta sección?

Cancelación

Extorno

Validación backend

Manejo por estado

​Request

​Path

​Headers

​Response

​Ejemplo: cancelación exitosa

​Ejemplo: extorno exitoso

​Siguiente paso

API de Consulta

Notificaciones

¿Qué cubre esta sección?

Request

Path

Headers

Response

Ejemplo: cancelación exitosa

Ejemplo: extorno exitoso

Siguiente paso