Anula un pago
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.
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.
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"}