Voids & Refunds - Kushki Developer Portal

Integra los servicios de Kushki para aceptar pagos presenciales en tu flujo actual o crea un flujo nuevo con los servicios que ofrecemos.

Importante

Recuerda que es necesario hacer los requests por HTTPS usando las credenciales que te entregamos. Es importante que no compartas datos sensibles en lugares públicos.

Las devoluciones pueden ser de tres tipos, según el día y la hora en que se procesan la transacción original y la solicitud de cancelación:

Tipo de servicio	Descripción
1. Reverso	Este request se envía cuando se supera el tiempo esperado de procesamiento de la transacción. Se genera cuando hay un problema al procesar la transacción y no se sabe si el cargo se hizo o no. Puede deberse a un problema de time out. El reverso debe hacerse el mismo día de la transacción.
2. Anulación	Se genera cuando se sabe que la transacción se procesó con éxito, pero se necesita una solicitud de anulación. La anulación se genera cuando la solicitud de devolución se procesa el mismo día en que se hizo la transacción, antes de las 22:59 (hora aproximada). Esta hora depende del corte que hace el procesador. Se hacen hasta 3 intentos de devolución con el procesador y, una vez aprobada la anulación, el cargo se quitará del estado de cuenta de tu cliente y se le devolverá el monto descontado.
3. Reembolso	Se genera cuando se sabe que la transacción se procesó con éxito, pero se necesita una solicitud de reembolso. El reembolso se genera cuando la solicitud de devolución: - Se procesa después de las 22:59 (hora aproximada) del día de aprobación de la transacción. - Cuando la solicitud de anulación superó los tres intentos. - Cuando la solicitud de devolución se hace un día distinto al de la transacción original. El tiempo máximo permitido para procesar un reembolso es de 120 días.

1. Reversos

Si hay problemas de comunicación o un time out y necesitas verificar si una transacción fue aprobada o rechazada, puedes hacer una operación de reverso para cancelar la transacción.

Nota

Los reversos solo están disponibles el mismo día en que se hizo la transacción, antes de las 22:59. Ten en cuenta que debes esperar al menos 1 minuto después de la transacción antes de iniciar un reverso.

Para reversar una transacción, debes consumir el endpoint /pos/v1/transaction y enviar Reverse en el campo transaction_mode, charge en el transaction_type y el client_transaction_id de la transacción que quieres reversar como parte del cuerpo del request.

Revisa el ejemplo de abajo:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 20,
    "currency": "PEN",
    "extra_taxes": {},
    "subtotal_iva": 0,
    "subtotal_iva0": 200
  },
  "country": "PER",
  "isDeferred": false,
  "is_cashback": false,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.18",
    "location": {
      "latitude": -1.2253600000000002,
      "longitude": -78.61997
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600003",
      "enc_track2": "2C5E3DC796759FAB00BB11163CC4B69B"
    },
    "enc_tlv": "E9BCEC77FACD77F942E433BE6CD27068F09ADFA082B6AE478D9BDA4EEEAFD3765300FD2EF030CD3A8DD9624E04CDFBC60B4206B9587A1A0DB5820D87D3ACAB9F8B14B35A8B8D7307AEBDCFD9D5DD8EB5DC7BFB729A1E6ABAC08D5C5A064F590F414D560C3EE964449B40D24B09703AE38FF45F328CC03A8A3ABCFBCDF0AFBCDAB674C87AC66CD842E7E9C36B6826ECAC8EB32E5E036787D4B50CD8C43F0C89918A23C396AEE4096805AE52DF13B343A6FDAC864CB27593C65B39B02239B707554357675ED96C3859",
    "pin_ksn": "FFFF4357486333600003",
    "reading_type": "ICC"
  },
  "transaction_mode": "Reverse",
  "transaction_type": "charge",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

Reverso sin tarjeta

Nota

Esta funcionalidad está actualmente en fase Beta en Perú.

Para hacer un reverso sin tarjeta, envía el campo omit_card con el valor true como en el siguiente ejemplo.

{
    "amount": {
        "currency": "PEN",
        "iva": 0,
        "subtotal_iva": 0,
        "subtotal_iva0": 6000
    },
    "transaction_mode": "Reverse",
    "transaction_type": "charge",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "omit_card": true
}

Consejo

En el campo transaction_type debes enviar el tipo de transacción que quieres reversar (capture, charge).

2. Anulación

La anulación se genera cuando la solicitud de devolución se procesa el mismo día de la transacción original, antes de las 22:59 para Perú (hora aproximada).

Para hacer anulaciones, debes consumir el endpoint /pos/v1/transaction y enviar Void en el transaction_mode y el transaction_reference de la transacción que quieres cancelar como parte del cuerpo del request, junto con el client_transaction_id de la transacción de anulación.

Anulación sin tarjeta

Nota

Esta funcionalidad está actualmente en fase Beta en Perú.

Para hacer una anulación sin tarjeta, envía el campo omit_card con el valor true como en el siguiente ejemplo.

{
    "amount": {
        "currency": "PEN",
        "iva": 0,
        "subtotal_iva": 0,
        "subtotal_iva0": 60000
    },
    "transaction_mode": "Void",
    "transaction_type": "charge",
    "is_smart_void": true,
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
    "omit_card": true
}

Consejo

En el campo transaction_type debes enviar el tipo de transacción que quieres anular (capture, charge, preAuth, reAuthorization).

3. Reembolsos

A través de la API de Kushki puedes solicitar el reembolso de una transacción previamente autorizada o de preautorizaciones.

Esta transacción se identifica por su número de referencia transaction_reference, que se genera una vez que el cargo se procesa con éxito.

Para reembolsos parciales, debes incluir el objeto amount en el request.

Para solicitar el reembolso de una transacción, debes consumir el endpoint pos/v1/refund, enviar Authorization en el parámetro transaction_mode, refund en el transaction_type y el transaction_reference de la transacción que quieres cancelar como parte del cuerpo del request, junto con el client_transaction_id de la transacción de reembolso.

Reembolso sin tarjeta

Para hacer un reembolso sin tarjeta, envía el campo omit_card con el valor true como en el siguiente ejemplo.

{
    "amount": {
        "currency": "PEN",
        "iva": 0.0,
        "subtotal_iva": 0.0,
        "subtotal_iva0": 600
    },
    "transaction_mode": "Authorization",
    "transaction_type": "refund",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
    "omit_card": true
}

Anulaciones y reembolsos

1. Reversos#

Reverso sin tarjeta#

2. Anulación#

Anulación sin tarjeta#

3. Reembolsos#

Reembolso sin tarjeta#

1. Reversos

Reverso sin tarjeta

2. Anulación

Anulación sin tarjeta

3. Reembolsos

Reembolso sin tarjeta