Cancel payments

October 30, 2024

When processing card-present payments with Kushki, you can process refunds, voids, or reversals for approved debit and credit card transactions. Once the refund, void, or reversal is approved, the funds will be returned to your customer’s bank account

Environments

Make any adjustments to your system by testing in a dev development environment. Remember that no real transactions will be processed in this environment.

When ready, you can switch to the live environment to process real transactions.

Cloud terminal API, App to app and Terminal SDK

Cancel a payment

A cancellation is generated when the refund request is processed on the same day as the original transaction, before 11:00 p.m. (Mexico City time, UTC -6). At the time of the cancellation, Kushki makes three refund attempts with the processor; if the request is successful, the purchase will disappear from your client’s statement and they will receive their funds once the request is approved.

You can cancel an authorization or an order identified by its transaction reference number. This value is provided when a payment is successful.

To cancel a payment, call the Cancel payments endpoint sending your user token and the ID of the transaction to cancel.

List of all properties available in the request:

Example of cancellation request:

{
  "saleId": "12200"
}

Response

If the information sent is correct, you will receive a JSON object that contains helpful information about the request.

Successful request example:

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

Error request example:

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

Please review the Transactions reference for more information.

Raw card-present API

How do voids and refunds work?

Through the card-present service, you can perform either of the following services, depending on your merchant needs:

Refunds are generated in two classes (voids or refunds) , depending on the day and time the original transaction was processed and the time the cancellation was generated. You can also request a cancellation of the transaction (reversal) in case there are communication problems and you need to validate if the transaction was approved or rejected.

We’ll tell you about the processing of these services below:

Perform reversals

If there are communication issues and you need to verify whether a transaction was approved or rejected, you can perform a reverse operation to cancel a transaction.

To reverse a transaction, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction and send Reverse in the transaction_mode field and the client_transaction_id of the transaction you want to reverse as part of the request body. Please follow the steps in the available API guide.

{
  "card": {
    "card_holder_name": "Jhon Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 12.34,
    "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"
}

Carrying out voids

A void is generated when the refund request is processed on the same day as the original transaction, before 22:00 (approximate time). When processing the void, Kushki makes three attempts to refund with the processor; if the request is successful, the purchase will disappear from your customer’s statement and they will receive their funds once the request is approved.

You can cancel the authorization or an order identified by its transaction reference number transaction_reference. This field is provided when a payment or a deferred payment is successfully made.

To make cancellations, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction and send Void in the transaction_type field and the transaction_reference of the transaction you are going to cancel as part of the request body. Please follow the steps in the guide available at the API.

The request you should send depends on the reading channel of your merchant’s POS terminal (chip, magnetic stripe, or contactless [NFC]). Check the example below:

{
  "card": {
    "card_holder_name": "John Doe/"
  },
  "amount": {
    "iva": 0,
    "tip": 12.34,
    "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": "Void",
    "transaction_type": "charge",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

Refunding a transaction

If it’s not possible to perform the void:

• Within the original day when the transaction was generated,
• After 22:00 hours (approximate time) on the day of transaction approval, or
• The three void attempts result in an error A refund will be generated, which may take up to 7 business days to process and up to 45 business days to reflect in your customer’s statement, according to the times and policies of the card issuer bank.

If it’s not possible to perform the void:

• Within the original day when the transaction was generated,
• After 23:59 hours (approximate time) on the day of transaction approval, or
• The three void attempts result in an error.

A refund will be issued, which may take up to 7 business days to process and up to 20 business days to appear in your customer’s statement, according to the processing times and policies of the card issuer bank.

Through the Kushki API, you can request a refund for a previously authorized transaction.

This transaction can be identified by its transaction reference number transaction_reference, which is generated once the charge is successfully processed.

For partial refunds, you need to include the amount object in the endpoint request.

To request a transaction refund, you need to consume the endpoint https://api-uat.kushkipagos.com/pos/v1/refund, following the steps available in the API.

The request you need to send depends on the reading channel of your merchant’s POS terminal (chip, magnetic stripe, or contactless [NFC] payments). Please review the examples below:

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