Voids,reverses, and refunds with card-present

August 23, 2024

Learn how to refund a payment or request the cancellation of a payment from your customers.

This functionality is available for the following models:

☑ Acquirer
☐ Aggregator

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

How do voids and refunds work?

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

Type of service	Description
Reversal	It is generated when there is a problem in the processing of the transaction and it is not known if the charge was made. This may be due to a time out problem. To request a reversal there is a time limit of 29 seconds, once the transaction to be reversed has been generated.
Void	It is generated when it is known that the transaction was processed successfully, but a void request is required. The void is generated when the refund request is processed on the same day as the transaction was made, before 23:59 (approximate time). This time depends on the cut-off performed by the processor. Up to 3 attempts of refund are made with the processor, and once the void is approved, the charge will be removed from your customer’s statement and the deducted amount will be refunded.
Refund	It is generated when it is known that the transaction was processed successfully, but a refund request is required. Refund is generated when the refund request: -Is processed after 23:59 (approximate time) of the approval day of the transaction. -When the void request exceeded three attempts. When the refund request is made on a different day than the original transaction. The maximum time allowed to process a refund is 120 days.

Refunds generated come in two types (voids or refunds ), depending on the day and time the original transaction was processed and when the void was generated. You can also request a void of the transaction (reversal) in case of communication issues and the need to verify whether 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.

// Chip
{
  "card": {
    "card_holder_name": "Jhon Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 12.34,
    "currency": "CLP",
    "extra_taxes": {},
    "subtotal_iva": 0,
    "subtotal_iva0": 2000
  },
  "country": "CHL",
  "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 23:59 (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.

Anulaciones tarjeta presente en

You can void 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-docs.kushkipagos.com/docs/card-present-payments/card-present-payments%2Foperations%2Fcreate-a-po-v-1-transaction And send charge in the transaction_type field, Void in the transaction_mode, and the transaction_reference of the transaction you want to cancel as part of the request body. Please follow the steps available in the Kushki API guide.

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

JSON
JSON
JSON

// Chip
{
  "card": {
    "card_holder_name": "CUST IMP MC 103"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "CLP",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 60999
  },
  "country": "CHL",
  "cvm_type": "none",
  "is_cashback": false,
  "is_deferred": false,
  "merchant_id": "0987654321",
  "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": "Void",
  "transaction_type": "charge",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

// Banda magnética 
{
  "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": 2000
  },
  "country": "CHL",
  "cvm_type": "Chip",
  "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": "Void",
  "transaction_type": "charge",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

// Pagos sin contacto
{
  "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": 2000
  },
  "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_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": "Void",
  "transaction_type": "charge",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

Refunding a transaction

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:

JSON
JSON
JSON

// Chip
{
  "card": {
    "card_holder_name": "CUST IMP MC 103"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "CLP",
    "extra_taxes": {
      "iac": 0,
      "ice": 0,
      "airport_tax": 0,
      "travel_agency": 0
    },
    "subtotal_iva": 0,
    "subtotal_iva0": 60000
  },
  "country": "CLP",
  "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"
}

// Banda magnética 
{
  "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"
}

// Pagos sin contacto (NFC) 
{
  "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_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"
}

Error codes

Find out what are the error codes for card present transactions.