Anula un pago

Web

Android

iOS

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente

☐ Agregador

¡Importante!

Ten en cuenta que, debido a nuestras políticas de riesgo, los medios de pago disponibles y el tipo de integración pueden variar al momento en que formalices la afiliación. Te indicaremos cómo proceder en caso de que este proceso aplique para tu comercio.

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

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.

Si requieres realizar anulaciones parciales, es necesario que envíes el importe en el objeto refundAmount.

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.
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 client_transaction_id 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.

Los reversos solo están disponibles el mismo día en que se realizó la transacción, antes de las 23:59 para Chile, 22:00 para México y 20:59 para Perú (hora aproximada). Ten en cuenta que debes esperar al menos 1 minuto después de la transacción antes de iniciar un reverso.

{
  "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"
}

El reverso siempre se procesará por el monto total de la transacción original, sin importar el valor indicado en la solicitud de reverso.

Operación disponible sin tarjeta ⛔️ 💳

Es posible realizar reversos omitiendo los detalles de la tarjeta. Para hacerlo, debes enviar el campo omit_card con valor de true. Consulta aquí el detalle de la trama de la transacción cuando se quiere omitir esta información.

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.

Importante

Las anulaciones parciales no están disponibles en México.

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"
  },
  "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"
}

Operación disponible sin tarjeta ⛔️ 💳

Es posible realizar anulaciones omitiendo los detalles de la tarjeta. Para hacerlo, debes enviar el campo omit_card con valor de true. Consulta aquí el detalle de la trama de la transacción cuando se quiere omitir esta información.

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.

Importante

Los reembolsos y anulaciones parciales no están disponibles en México.

Ten en cuenta que las transacciones locales en México tienen un tiempo máximo de 15 días calendario para generarse el reembolso.

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

{
  "card": {
    "card_holder_name": "CUST IMP MC 103"
  },
  "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"
}

Operación disponible sin tarjeta ⛔️ 💳

Es posible realizar reembolsos omitiendo los detalles de la tarjeta. Para hacerlo, debes enviar el campo omit_card con valor de true. Consulta aquí el detalle de la trama de la transacción cuando se quiere omitir esta información.

Anula un pago

Ambientes#

Cloud terminal API, App to app y Terminal SDK#

Anula un pago#

Respuesta#

Raw card-present API#

¿Cómo funcionan las anulaciones y reembolsos?#

Realizar reversiones#

Realizar anulaciones (Voids)#

Reembolsar una transacción#

Ambientes

Cloud terminal API, App to app y Terminal SDK

Anula un pago

Respuesta

Raw card-present API

¿Cómo funcionan las anulaciones y reembolsos?

Realizar reversiones

Realizar anulaciones (Voids)

Reembolsar una transacción