Anula un pago

04 diciembre 2024

Web

Android

iOS

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente
☐ Agregador

Al procesar pagos de tarjeta presente con Kushki puedes procesar reembolsos, anulaciones o reversos de pagos con tarjeta de débito y tarjeta de crédito en estado aprobado. Al momento en que se apruebe el reembolso, anulación o reverso, los fondos se devolverán a la cuenta bancaria de tu cliente.

Ambientes

Realiza todas las adecuaciones a tu sistema mediante pruebas en el ambiente de desarrollo dev. Recuerda que en este ambiente no se procesarán transacciones reales.

Cuando estés listo, podrás cambiar al ambiente de producción live para procesar transacciones reales.

Ambiente	Url base	Disponibilidad
`dev`	https://valquiria.billpocket.dev	Cloud Terminal API, App to app y Terminal SDK
`dev`	https://api-uat.kushkipagos.com	Raw Card-Present API
`live`	https://valquiria.billpocket.com	Cloud Terminal API, App to app y Terminal SDK
`live`	https://api.kushkipagos.com	Raw Card-Present API

Cloud terminal API, App to app y Terminal SDK

Anula un pago

Una anulación se genera cuando la solicitud de devolución es procesada el mismo día de la transacción original, antes de las 23:00 horas (hora ciudad de México, UTC -6). Al momento de realizar la anulación, Kushki realiza tres intentos de devolución con el procesador; en caso de que la solicitud sea exitosa, la compra desaparecerá del extracto de movimientos de tu cliente y este recibirá sus fondos una vez aprobada la solicitud.

Anulaciones tarjeta presente

Puedes anular la autorización o una orden identificada por su número de referencia de la transacción. Este valor es proporcionado cuando un pago se realiza correctamente.

Para anular un pago, consume el endpoint Cancel payments enviando tu token de usuario y el id de la transacción a anular.

Lista de todas las propiedades disponibles en la solicitud:

Propiedad	Tipo	Requerido	Descripción
saleId	String	Sí	Id de la transacción a anular.
refundAmount	Number	No	Envía un monto menor a la venta para procesar una anulación parcial.
uniqueReference	String	No	Referencia única generada de tu lado para evitar duplicados.

Ejemplo de solicitud de anulación:

{
  "saleId": "12200"
}

Respuesta

Si la información enviada es correcta, recibirás un objeto json el cuál contendrá información útil de la solicitud.

Ejemplo de solicitud exitosa:

{
  "message": {
    "statusInfo": "APROBADA",
    "status": "1",
    "transactionId": "129058",
    "autorization": "N/D"
  },
  "statusCode": 200,
  "error": null
}

Ejemplo de solicitud de error:

{
  "message": [
    "saleId must be a string"
  ],
  "responseCode": "002"
}

Revisa la referencia de Transacciones para más información.

Raw card-present API

¿Cómo funcionan las anulaciones y reembolsos?

A través del servicio de tarjeta presente, podrás realizar alguno de los siguientes servicios, de acuerdo a la necesidad de tu comercio:

Tipo de servicio	Descripción
Reversión o reverso	Se genera cuando existe un problema en el procesamiento de la transacción y se desconoce si se realizó el cargo. Esto puede deberse a un problema de time out. Esto puede deberse a un problema de time out. Para solicitar una reversión se tiene un tiempo límite de 29 segundos, una vez generada la transacción que se desea reversar.
Anulación	Se genera cuando se conoce que la transacción se procesó de manera exitosa, pero se requiere realizar una solicitud de anulación. La anulación se genera cuando la solicitud de devolución se procesa el mismo día en que la transacción fue realizada, antes de las 22:00 (hora aproximada). Esta hora depende del corte realizado por el procesador. Se realizan hasta 3 intentos de devolución con el procesador y una vez aprobada la anulación, el cargo se eliminará del extracto de tu cliente y el valor descontado se devolverá.
Reembolso	Se genera cuando se conoce que la transacción se procesó de manera exitosa, pero se requiere realizar una solicitud de devolución. El reembolso se genera cuando la solicitud de devolución: -Se procesa luego de las 22:00 (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 realizó durante un día diferente al de la transacción original. -El tiempo máximo habilitado para realizar un reembolso es de 120 días.

Las devoluciones generadas son de dos clases (anulaciones o reembolsos) , de acuerdo con el día y la hora en que la transacción original fue procesada y el tiempo en que se generó la anulación. También puedes solicitar una anulación de la transacción (reverso) en caso de que hayan problemas de comunicación y necesites validar si la transacción fue aprobada o rechazada.

Te contamos sobre el procesamiento de estos servicios a continuación:

Realizar reversiones

En caso de que hayan problemas de comunicación y necesites validar si una transacción fue aprobada o rechazada, puedes realizar una operación inversa para anular una transacción.

Para revertir una transacción, es necesario que consumas el endpoint https://api-uat.kushkipagos.com /pos/v1/transaction y que envíes Reverse en el campo transaction_mode y el transaction_reference de la transacción que vas a revertir como parte del cuerpo del requerimiento. Por favor sigue los pasos de la guía disponible en la API.

{
  "card": {
    "card_holder_name": "Jhon Doe/"
  },
  "amount": {
    "iva": 0,
    "tip": 10000,
    "currency": "MXN",
    "extra_taxes": {},
    "subtotal_iva": 0,
    "subtotal_iva0": 2000
  },
  "country": "MEX",
  "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"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "1111111",
    "second_last_name": ""
  },
  "transaction_mode": "Reverse",
  "transaction_type": "charge",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

Realizar anulaciones (Voids)

Una anulación se genera cuando la solicitud de devolución es procesada el mismo día de la transacción original, antes de las 22:00 (hora aproximada). Al momento de realizar la anulación, Kushki realiza tres intentos de devolución con el procesador; en caso de que la solicitud sea exitosa, la compra desaparecerá del extracto de movimientos de tu cliente y este recibirá sus fondos una vez aprobada la solicitud.

Anulaciones tarjeta presente

Puedes anular la autorización o una orden identificada por su número de referencia de la transacción transaction_reference. Este campo es proporcionado cuando un pago o un pago diferido se realiza correctamente.

Para hacer cancelaciones, es necesario que consumas el endpoint https://api-uat.kushkipagos.com /pos/v1/transaction y que envíes Void en el campo transaction_mode y el transaction_reference de la transacción que vas a cancelar como parte del cuerpo del requerimiento. Por favor sigue los pasos de la guía disponible en la API.

El requerimiento que debes enviar depende del canal de lectura de la terminal POS de tu comercio (chip, banda magnética o pagos sin contacto contactless [NFC]). Revisa el ejemplo a continuación:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 10000,
    "currency": "MXN",
    "extra_taxes": {},
    "subtotal_iva": 0,
    "subtotal_iva0": 200000
  },
  "country": "MEX",
  "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"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "1111111",
    "second_last_name": ""
  },
  "transaction_mode": "Void",
  "transaction_type": "charge",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

Reembolsar una transacción

Si no es posible realizar la anulación:

Dentro del día original en el que la transacción fue generada,
Después de las 22:00 horas (hora aproximada) del día de aprobación de la transacción, o
Los tres intentos de anulación generan un error

Se generará un reembolso; el cual puede tardar hasta 7 días hábiles en procesarse y hasta 45 días hábiles en reflejarse en el extracto de tu cliente, de acuerdo con los tiempos y políticas del banco emisor de la tarjeta.

A través del API de Kushki puedes solicitar el reembolso de una transacción que fue autorizada previamente.

Esta transacción puede identificarse por su número de referencia de transacción transaction_reference, el cual es un identificador que se genera una vez el cargo se realiza correctamente.

Para reembolsos parciales, es necesario que envíes en el endpoint el objeto amount.

Para solicitar el reembolso de la transacción, es necesario que consumas el endpoint https://api-uat.kushkipagos.com /pos/v1/refund, siguiendo los pasos de la guía disponible en la API.

El requerimiento que debes enviar depende del canal de lectura de la terminal POS de tu comercio (chip, banda magnética o pagos sin contacto contactless [NFC]). Revisa los ejemplos a continuación:

JSON
JSON
JSON

{
  "card": {
    "card_holder_name": "CUST IMP MC 103"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "MXN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "MEX",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.26",
    "location": {
      "latitude": -0.22480833333333333,
      "longitude": -78.487955
    },
    "has_print": true,
    "terminal_id": "PB04216R20537"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "ICC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "-1",
    "document_number": "",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "refund",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

{
  "card": {
    "card_holder_name": "C92546CB8524197A17A1B960D5D09A01ABBE63E5478FD5155DBE2B18824771046EEA135D73B192236937AF33E781B81804098835D3A1AD81A863BAEA3BAA42E4"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "CLP",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 20000
  },
  "country": "CHL",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.13",
    "location": {
      "latitude": -0.1848534,
      "longitude": -78.4769761
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track1": "06056D9EE9D77E4D846912F77C0B37C5FC6A95D1DF21DD502D3A08E8141CF82818F5DC4FA7637F400EA488D388F2B70F8A22EAEFBBEEDDE93A118BFB789BD8C0",
      "enc_track2": "FD580B3BBFCCB821EAB4AB64947C4632C0BE6C70AB4ECDE4"
    },
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "MCR"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "123666",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "refund",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

{
  "card": {
    "card_holder_name": "C92546CB8524197A17A1B960D5D09A01ABBE63E5478FD5155DBE2B18824771046EEA135D73B192236937AF33E781B81804098835D3A1AD81A863BAEA3BAA42E4"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "MXN",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 20000
  },
  "country": "MEX",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.13",
    "location": {
      "latitude": -0.1848534,
      "longitude": -78.4769761
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0A53CE9AF633A510E66C8031171AAFCF8CE29857B19101326ED67512533B86C51ED16C5E624DA97EDA72864A39763822418FCAC5439D2F1F72F6FC0BAA6EED37630767D9D161612654E49944FC435525C6C356177B1BD0A545C19FF5E47685E35B02B20B307BDE2A26FAD2F42D7CB00BE9C53FD05BECE71110919ADE3158398B8B02003F682374B942C4B6D7FD54DE2B65A9C66125DF28A80",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "NFC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "123666",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "refund",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}