Operaciones de transacciones

Si está integrado en el motor de pagos a través de API, puede utilizar las operaciones de API para procesar transacciones, recuperar detalles de transacciones, almacenar detalles de tarjetas, etc. Para realizar una operación, debe tener el privilegio requerido en su perfil del negocio con el motor de pagos. Para comprobar qué operaciones tiene disponibles, póngase en contacto con su proveedor de servicios de pago.

La funcionalidad disponible para usted se limita a la capacidad de los adquirentes configurados en su perfil de negocio con el motor de pagos. Cuando el adquirente no soporta una función en el motor de pagos, el motor de pagos (de ese adquirente) rechazará cualquier solicitud de operación para ejecutar dicha función.
Los detalles de pago en las solicitudes de transacción, cuando se admiten, pueden proporcionarse a través de varias fuentes. Consulte Diversas fuentes de detalles de pago.

Operaciones de transacciones iniciales

Esta sección describe las operaciones que puede usar para iniciar una transacción.

Authorize

La operación Authorize verifica los detalles de la tarjeta del pagador, revisa que el pagador tenga suficientes fondos disponibles en su línea de crédito e intenta reservar los fondos solicitados. El límite de crédito del pagador se reduce de acuerdo con el monto autorizado y los fondos se reservan por un período de tiempo (en la mayoría de los casos de 5 a 8 días), según lo que determinen el esquema de la tarjeta y las reglas de emisión de la tarjeta del pagador.

La autorización no debita fondos desde la cuenta del pagador, sino que reserva el monto total del pedido, lista para que la operación Capture debite la tarjeta y transfiera los fondos a su cuenta. Las transacciones de Authorize no aparecen en el estado de cuenta del pagador, a diferencia de las transacciones de Capture.

Para una autorización con éxito, el motor de pagos devuelve result=SUCCESS en la respuesta de transacción. Puede realizar Authorize como operación subsiguiente solo si la transacción inicial es Verify y los detalles de tarjeta en la solicitud Authorize y en la transacción Verify coinciden.

Authorize también se conoce como "Auth", "Authorization".

Para algunos pagos mediante explorador, puede iniciar una operación Authorize a través de la operación Initiate Browser Payment. Para obtener más información, consulte Implementación de integración de pago mediante explorador.

Certeza de pedido

Puede indicar un nivel de certeza sobre el monto de la autorización que se capturará, al proporcionar el campo order.certainty en la solicitud Authorize. Para hacer esto, su proveedor de servicios de pago debe haber habilitado el privilegio "Cambiar certeza de pedido" en su perfil de negocio. Puede configurar el campo en cualquiera de los siguientes valores:

  • FINAL: se espera que el monto autorizado completo se capture, con una o más capturas, dentro del tiempo indicado (por lo general, 7 días). El pedido solo se cancelará en circunstancias excepcionales (por ejemplo, el pagador canceló su compra). Proporcionar este valor en su transacción puede calificar la transacción para tarifas de procesamiento menores.
  • ESTIMADO: el monto autorizado es una estimación del monto que se va a capturar dentro del tiempo estipulado en el mandato (por lo general, de 30 a 31 días). Es posible que el monto capturado sea menor o que no se capture nada, o que la autorización se cancele. Si se proporciona este valor en la transacción, el costo de las tarifas de procesamiento puede ser superior.

La solicitud se rechaza si usted no tiene el privilegio para cambiar la certeza del pedido y el valor que ingresa en este campo no coincide con el valor predeterminado de certeza del pedido configurado en su perfil del negocio.

Referencia de API de Authorize [REST][NVP]

Vencimiento de la autorización

Las autorizaciones tienen un período de validez después del cual vencen. El período de validez de la autorización (en milisegundos) puede configurarse en el motor de pagos para una combinación de adquirente, tipo de tarjeta y certeza de pedido.

Cuando envía una solicitud de Authorize al motor de pagos, este determina la fecha y hora de vencimiento de la autorización, sobre la base del período configurado de validez de la autorización (utilizando la combinación tipo de tarjeta, adquirente, certeza de pedido). Cuando esto sea compatible con el adquirente, el vencimiento de la autorización se devuelve en el campo authorizationResponse.autoExpiry en la respuesta de la operación Retrieve Transaction. Este campo contiene la fecha y la hora en que el motor de pagos hará que la autorización venza automáticamente.

Una vez que el período de validez de la autorización venza, el motor de pagos hará lo siguiente:

  • rechazar cualquier solicitud de Capture con respecto al pedido;
  • intentará anular automáticamente la autorización y liberará los fondos para el pagador (cuando esto sea compatible con el adquirente). Para esto, su proveedor de servicios de pago debe haber habilitado el privilegio "Habilitar reversos de autorización automáticos" en su perfil de negocio.

    Si el pedido ya fue capturado parcialmente y si su adquirente admite la anulación de autorizaciones para capturas parciales, el motor de pagos intentará anular/revertir el monto de autorización pendiente.

Actualización de autorización

El motor de pagos puede actualizar períodos de autorización o incrementar el monto de autorización para autorizaciones válidas si el adquirente lo admite. Para esto, su proveedor de servicios de pago debe habilitar el privilegio "Update Authorization" en su perfil del negocio. Para obtener más información, consulte Update Authorization.

Preguntas frecuentes

¿Qué pasa si deseo capturar mi autorización solo parcialmente?

Al enviar una solicitud de captura para un pedido, puede proporcionar un monto de captura inferior al monto autorizado para el pedido (order.AuthorizedAmount).

Si no tiene intención de capturar el monto autorizado restante, puede anular el monto autorizado pendiente, si el adquirente lo admite.

Puede proporcionar el número previsto de capturas para el pedido en el campo order.expectedNumberOfCaptures en la solicitud de Capture o mediante la IU de Administración de negocios. En caso de que el número total de capturas para el pedido (incluida la captura actual) sea superior o igual al número total previsto de solicitudes de Capture, el motor de pagos activará automáticamente una anulación del monto autorizado pendiente, si el adquirente lo admite.

El campo order.expectedNumberOfCaptures solo se puede enviar a partir de la versión 44 de API.
¿Qué pasa si ya no deseo capturar mi autorización?

Puede anular su autorización al enviar una solicitud VOID con el ID de transacción para la autorización que se debe anular en el campo transaction.targetTransactionId.

¿Qué pasa si tengo que capturar más de lo que he autorizado?

Para capturar un monto superior al autorizado para un pedido, su perfil de negocio en el motor de pagos debe estar habilitado para el privilegio Captura excesiva. Consulte Capturas excesivas

¿Puedo capturar una autorización que haya realizado fuera del motor de pagos?

Sí, esto se conoce como una solicitud de captura independiente y, cuando se admite para el adquirente, simplemente se puede enviar una solicitud de captura con el código de autorización devuelto por el adquiriente (en la respuesta de autorización).

Pay

La operación Pay combina eficazmente una operación Authorize y una operación Capture en un mensaje. Una transacción única autoriza el pago y transfiere fondos desde la cuenta del pagador a su cuenta.

Si desea enviar Pay como operación subsiguiente, debe tener una transacción de verificación correcta y los detalles de la tarjeta en la solicitud Pay y en la transacción Verify deben coincidir.

El nivel de certeza para una transacción Pay se define en FINAL. Para obtener más información, consulte Certeza de pedido.

Pay también se conoce como "Sale", "Purchase".

Para algunos pagos mediante explorador, por ejemplo PayPal, Giropay, Sofortbanking, etc., puede iniciar una operación Pay a través de la operación Initiate Browser Payment. Para obtener más información, consulte Implementación de integración de pago mediante explorador.

Referencia de API de Pay [REST][NVP]

Auto Capture

Auto-capture es una variante de la operación Pay, que permite que un negocio con un privilegio para realizar una transacción Pay y que usa un adquirente que solo admite las transacciones Authorize/Capture pueda realizar una operación Authorize, seguida de una operación Capture activada en forma automática. Con este tipo de transacción, una solicitud Pay se transforma en las operaciones Authorize y Capture.

Esta operación se puede realizar mediante el uso de Direct Payment, Hosted Session, o los modelos de integración Batch.

El identificador de transacción para las solicitudes Authorize y Capture será el identificador de transacción proporcionado por usted en la solicitud Pay original. En la respuesta Pay, el campo transaction.type indicará la última transacción con la que se intentó satisfacer la solicitud, es decir, Authorize o Capture.

Puede usar la operación Retrieve para recuperar los resultados de una operación capturada automáticamente. Esto devuelve los resultados de la última transacción con la cual se intentó satisfacer la solicitud.

Puede usar la operación Void Pay para anular una transacción Pay capturada automáticamente. Cuando realiza esta operación, Mastercard Payment Gateway:

  • Intenta "Void Capture" para la transacción Capture.
  • Si "Void Capture" es satisfactorio, entonces se intenta "Void Authorization" para la operación Authorization. Si "Void Capture" no es satisfactorio, entonces la respuesta indica que la anulación no se pudo realizar y no se intenta Void Authorization.
Auto-Capture también se puede realizar en una transacción Authorize referida, al proporcionar el código de autorización manual.
Verify

La operación Verify le permite verificar los detalles de la cuenta del pagador antes de realizar una transacción Pay o Authorize. También comprueba los detalles de pago mediante un método de verificación reconocido por el adquirente. Por ejemplo, si el adquirente cuenta con el Servicio de verificación de dirección (AVS), entonces Verify envía una transacción para el AVS solamente, con un monto cero y los detalles de la dirección del pagador.

Referencia de API de Verify [REST][NVP]

Captura independiente

Una transacción de Captura independiente es una transacción Capture en la que la autorización se realizó de manera externa al motor de pagos. Al enviar una Captura independiente al motor de pagos, debe proporcionar el código de autorización generado de forma externa en el campo transaction.authorizationCode y los demás campos obligatorios.

Puede enviar Capturas independientes si tiene habilitado el privilegio Capture en su perfil del negocio.

El código de autorización es opcional para las transacciones con un origen de transacción "CARD_PRESENT". Esto permite que la Captura independiente se efectúe en pagos con tarjeta presente autorizados sin conexión.

Referencia de API de Captura independiente [REST][NVP]

Reembolso independiente

Una transacción de Reembolso independiente es una transacción Refund que le permite transferir fondos desde su cuenta de vuelta al pagador, sin una compra previa. Se pueden realizar Reembolsos independientes cuando desea dar crédito a la cuenta del pagador sin asociar el crédito a una transacción anterior.

Referencia de API de Reembolso independiente [REST][NVP]

Operaciones posteriores

Esta sección describe las operaciones que puede realizar en las transacciones iniciales, Authorize o Pay.

Para comprobar cuáles operaciones están configuradas en su perfil del negocio, póngase en contacto con su proveedor de servicios de pago.

Las operaciones posteriores son compatibles a través de Direct Payment o los modelos de integración de Batch.
Update Authorization

Esta operación permite actualizar una autorización válida existente para el período de autorización o el monto de autorización, si el adquirente lo admite.

Si actualiza la autorización para el mismo monto que el del pedido original, el período de autorización de la autorización existente se amplía en consecuencia. La fecha y hora de vencimiento de la autorización actualizada se devuelven en el campo authorizationResponse.autoExpiry en la respuesta de la operación Retrieve Transaction.

Si el monto proporcionado es superior al monto de la autorización existente, se actualiza el monto de autorización con el monto nuevo. Por ejemplo, si el monto de autorización existente es de 100 USD y se indica 120 USD como monto del pedido en la solicitud de Update Authorization, entonces el nuevo monto de autorización disponible para la captura será de 120 USD.

Si el monto proporcionado es inferior al monto de la autorización existente, se actualiza el monto de autorización con el monto nuevo. Por ejemplo, si el monto de autorización existente es de 100 USD y se indica 80 USD como monto del pedido en la solicitud de Update Authorization, entonces el nuevo monto de autorización disponible para la captura será de 80 USD. El motor de pagos procesa automáticamente una solicitud de reverso por el monto de autorización restante de 20 USD (cuando el adquiriente lo admita).

Tenga en cuenta que el motor de pagos solo puede actualizar una autorización existente si se cumplen las siguientes condiciones:

  • Su proveedor de servicios de pago debe habilitar su perfil del negocio en el motor de pagos para el privilegio "Update Authorization".
  • La certeza del pedido en el pedido debe estar establecida en ESTIMADA.
  • La moneda del pedido debe coincidir con la moneda utilizada en la autorización existente.
  • La autorización existente debe ser válida, correcta y debe estar totalmente aprobada.
  • La autorización existente no debe estar vencida, anulada ni capturada parcialmente/totalmente.

Totales del pedido

Tras una solicitud Update Authorization correcta (para una tarjeta o para PayPal), el monto del pedido (order.amount) y el monto total autorizado (order.totalAuthorizedAmount) se actualizan con el monto de la transacción (transaction.amount) de Update Authorization. Esto se aplica independientemente de si la transacción Update Authorization se envió al adquirente o de si el motor de pagos la aprobó automáticamente (response.gatewayCode=APPROVED_AUTO). No obstante, si se opta por ignorar la actualización de autorización para una solicitud de captura excesiva (enviando transaction.authorizationAdjustmentActions=NO_ACTION, consulte Capturas excesivas) y el motor de pagos envía una captura excesiva al adquirente, los totales del pedido NO se actualizan.

La aprobación automática de solicitudes Update Authorization por parte del motor de pagos (response.gatewayCode=APPROVED_AUTO) solo es aplicable cuando el monto proporcionado es mayor que el monto de la autorización existente.

Subtotales del pedido

Puede proporcionar los siguientes montos subtotales en la solicitud Update Authorization para pagos con tarjeta o PayPal:

  • order.itemAmount
  • order.shippingAndHandlingAmount
  • order.taxAmount
  • order.discount.amount (solo pagos con tarjeta)
  • order.gratuityAmount (solo pagos con tarjeta)
No se puede proporcionar order.cashbackAmount en la solicitud Update Authorization.

El motor de pagos NO valida si los montos del subtotal dan como total el transaction.amount (es decir, order.amount); sin embargo, debe asegurarse de ello para los pagos con PayPal.

Recargo

Puede actualizar un monto de recargo en la solicitud Update Authorization utilizando cualquiera de los siguientes campos:

  • order.surchargeAmount: utilice este campo si proporciona un recargo calculado previamente.
  • order.netAmount: utilice este campo si el motor de pagos calcula el monto del recargo (según sus reglas de recargo).
Para pagos con PayPal, no se puede proporcionar order.surchargeAmount y las solicitudes con este campo se rechazarán. Si proporciona order.netAmount en un pago con PayPal, la transacción se procesará sin que se aplique un recargo.

Referencia de API de Update Authorization [REST][NVP]

Capture

La operación Capture usa la autorización obtenida después de la operación Authorize inicial para transferir fondos desde la cuenta del pagador a su cuenta. Una operación Capture siempre debe ir precedida por una autorización exitosa y, como mínimo, se debe enviar un ID de autorización con la solicitud Capture. La moneda usada al capturar un monto debe coincidir con la moneda usada en la transacción de autorización.

Desde API versión 15 en adelante, si desea capturar fondos contra una autorización exitosa realizada mediante el motor de pagos , entonces, NO proporcione detalles de tarjeta en su solicitud Capture.

Las operaciones Capture normalmente son hechas por lote por el motor de pagos o por el host del adquirente, de manera que los fondos en efecto no se transfieren hasta que el lote se cierra y se produce la liquidación.

Capture también se conoce como "Bill", "Complete".

Captura excesiva

El monto total que usted capture puede sobrepasar el monto autorizado original si se habilita el privilegio de captura excesiva en el perfil del negocio.

La captura excesiva es una variación de captura en que usted realiza capturas de montos mayores que el monto autorizado. El exceso permitido se especifica como un porcentaje del monto autorizado original y lo determina su proveedor de servicios de pago.

Cuando se envíe una solicitud de captura excesiva, el motor de pagos intentará actualizar automáticamente el monto de autorización al monto que se desee capturar. Si el adquirente permite la actualización de autorizaciones, el motor de pagos envía la solicitud Update Authorization al adquirente. Si no, el motor de pagos aprobará automáticamente una actualización de autorización (hasta el límite de captura excesiva configurado para el perfil del negocio).

Envíe transaction.authorizationAjustmentAction=NO_ACTION en la solicitud de captura si no quiere que el motor de pagos intente actualizar la autorización antes de enviar la captura al adquirente. Tenga en cuenta que cuando el valor de autorización no coincida con la captura es posible que el pedido no tenga protección de contracargo.

Referencia de API de Capture [REST][NVP]

Refund

Refund le permite dar crédito a fondos para un pedido existente de vuelta en la cuenta del pagador. Las operaciones Refund solo se pueden realizar donde se ha completado una transferencia de fondos a través de operaciones Pay o Capture. Usted puede realizar cualquier número de transacciones de reembolso sobre la transacción original, pero no puede reembolsar más que el total que se haya obtenido mediante todas las transacciones de compra o captura asociadas con el pedido.

Se realizan reembolsos por muchos motivos, por ejemplo, la devolución de mercancía no deseada, incorrecta o con falla.

Desde API versión 15 en adelante, si desea reembolsar contra una transacción Capture o Pay realizada correctamente mediante el motor de pagos, entonces NO debe proporcionar los detalles de la tarjeta en su solicitud Refund.
Reembolso excesivo

El monto total reembolsado por un pedido puede sobrepasar el monto que se capturó correctamente para un pedido si se habilita el privilegio de reembolso excesivo en el perfil del negocio.

El exceso permitido sobre el monto capturado para transacciones API se puede configurar en función de cada moneda, en Ajustes de integración en Administración de negocios. Si no establece un límite de reembolso excesivo para una moneda, se rechazarán los reembolsos excesivos para pedidos en esa moneda.

Cuando se envía un reembolso, el monto total reembolsado para el pedido (incluso el reembolso intentado) no debe superar el monto total capturado para ese pedido por sobre el exceso máximo permitido. Por ejemplo, si envía un reembolso excesivo mediante API para un pedido donde el monto total capturado es de $100 USD y estableció el límite de reembolso excesivo para transacciones API en $20 USD, entonces puede reembolsar hasta $120 USD.

Esta función está disponible para pedidos realizados a través de Administración de negocios y API. Para reembolsos enviados mediante Administración de negocios, el exceso permitido para el pedido se verifica contra el límite de reembolso establecido para el operador en los Ajustes de operador en Administración de negocios.

Referencia de API de Refund [REST][NVP]

Retrieve Transaction

Retrieve Transaction le permite recuperar los detalles de una transacción mediante el ID de pedido y el ID de transacción. Ambos son obligatorios, ya que el ID de transacción identifica una transacción dentro de un pedido.

Referencia de API de Retrieve Transaction [REST][NVP]

Retrieve Order

Retrieve Order le permite recuperar los detalles de un pedido y todas las transacciones relacionadas con el pedido.

Referencia de API de Retrieve Order [REST][NVP]

Void

Void intenta eliminar/revertir inmediatamente una solicitud de transacción. Las anulaciones solo se pueden realizar en transacciones que el adquirente aún no ha enviado al banco, para procesarse al final del día. Una vez que el adquirente ha enviado una transacción para su procesamiento, usted debe realizar una operación Refund en lugar de una operación Void.

Puede anular transacciones Authorize, Capture, Pay o Refund. Una anulación realizada en una transacción Authorize liberará de inmediato cualquier fondo reservado. En todos los otros tipos de transacciones, la anulación evitará que ocurra la transferencia de fondos.

Referencia de API de Void [REST][NVP]

Referral

La operación Referral vuelve a enviar una transacción inicial referida (transacción Authorization o Pay que recibe la respuesta "Consultar al emisor" por parte del adquirente) como una nueva transacción Authorization o Pay con un código de autorización obtenido de parte del emisor.

Es posible que se requiera que el pagador proporcione información adicional para que el emisor apruebe la transacción y proporcione un código de autorización/ID de autorización manual.

Referencia de API de Transacción Referral[REST][NVP]

Contracargo

Se produce un contracargo cuando un pagador disputa un pago realizado a usted. Por ejemplo, no se recibieron los bienes o el pagador no autorizó el pago. Su proveedor de servicios de pago puede importar los detalles de las transacciones de contracargo al motor de pagos para que usted pueda usarlas en actividades de búsqueda y reportería. Su proveedor de servicios de pago puede registrar cada transacción de contracargo contra el pedido original o crear un nuevo pedido con una transacción de contracargo independiente.

Si comparte su Número SE/ID de negocio de banco (el identificador que su banco adquiriente le asigna) en múltiples perfiles de motor de pagos, se creará una transacción de contracargo independiente para cada perfil.

El motor de pagos puede crear múltiples transacciones de contracargo para un solo pedido. Puede realizar transacciones posteriores en un pedido que contenga una transacción de contracargo, por ejemplo, anulaciones o reembolsos.

Una transacción de contracargo registrada correctamente devolverá los siguientes campos en la respuesta Retrieve Transaction/Retrieve Order:

  • order.status=CHARGEBACK_PROCESSED o DISPUTED: cuando se crea una transacción de contracargo, se actualiza el estado del pedido correspondiente para representar que el pagador presentó una disputa.
    • order.status=DISPUTED indica que se presentó una disputa, pero aún no se han movido fondos.
    • order.status=CHARGEBACK_PROCESSED indica que se procesó una reclamación de contracargo y que los fondos se moverán desde o hacia la cuenta del negocio.
  • order.chargeback.amount
  • order.chargeback.currency
  • Grupo de parámetros de transaction.dispute: información sobre la disputa de contracargo, por ejemplo, evento de disputa, fecha, etc.
  • transaction.type=CHARGEBACK
  • transaction.source=SERVICE_PROVIDER
  • gatewayEntryPoint=SERVICE_PROVIDER_API
El motor de pagos registra las transacciones de contracargo solo con fines informativos; la transacción no se envía para el procesamiento posterior al adquirente.

Referencia de API de Transacción contracargo[REST][NVP]

Derechos de autor © 2020 Mastercard