Cancel payments

Web

Android

iOS

This functionality is available for the following models:

☑ Acquirer

☐ Aggregator

¡Important!

Please note that, due to our risk policies, the available payment methods and integration type may vary at the time you formalize the affiliation. We will inform you of the steps to follow if this process applies to your merchant.

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.

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

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.

If you need to make partial cancellations, you need to send the amount in the refundAmount object.

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:

Property	Type	Required	Description
saleId	String	Yes	Transaction ID to cancel.
refundAmount	Number	No	Submit an amount less than the sale amount to process a partial cancellation.
uniqueReference	String	No	Unique reference generated on your side to avoid duplicates.

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:

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.
Void	It is generated when it is known that the transaction was successfully processed, but a void request is required. The void is generated when the refund request is processed on the same day the transaction was made, before 22:00 (approximate time).. This time depends on the cutoff performed by the processor. Up to 3 attempts are made to refund 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 successfully processed, but a refund request is required. The refund is generated when the refund request: - Is processed after 22:00 (approximate time) on the day of transaction approval. -When the void request exceeds three attempts. - When the refund request is made on a different day from the original transaction. -The maximum time allowed to make a refund is 120 days.

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 call the endpoint https://api-uat.kushkipagos.com/pos/v1/transaction and send Reverse in the transaction_mode field, along with the client_transaction_id of the transaction you want to reverse as part of the request body. Please follow the steps in the guide available in the API.

Reversals are only available on the same day as the transaction was made, before 23:59 for Chile, 22:00 for Mexico, and 20:59 for Peru (approximate time). Please note that you must wait at least 1 minute after the transaction before initiating a reversal.

{
  "card": {
    "card_holder_name": "Jhon 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": "Reverse",
   "transaction_type": "charge",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

The reversal will always be processed for the full amount of the original transaction, regardless of the amount specified in the reversal request.

Operation available without card ⛔️ 💳

It is possible to process reversals without including card details. To do so, you must send the omit_card field with a value of true. See the details of the transaction structure here when omitting this information.

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.

Important

Partial refunds and voids are not available in Mexico.

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/"
  },
  "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",
       "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "client_transaction_id": "cffd9e13-993d-4d8b-9862-3ac4c0f63dec"
}

How to get the transaction reference in the Cloud terminal solution?

Voids and refunds require the transaction_reference field. This is returned in transactions processed using the status query service with idempotency Request status (idempotency).

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.

Important

Partial refunds and voids are not available in Mexico.

Please note that local transactions in Mexico have a maximum time of 15 calendar days to initiate the refund.

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

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

Operation available without card ⛔️ 💳

It's possible to perform refunds by omitting the card details. To do this, you need to send the omit_card field with a value of true. Check here the details of the transaction frame when you want to omit this information.

Environments#

Cloud terminal API, App to app and Terminal SDK#

Cancel a payment#

Response#

Raw card-present API#

How do voids and refunds work?#

Perform reversals#

Carrying out voids#

Refunding a transaction#

Environments

Cloud terminal API, App to app and Terminal SDK

Cancel a payment

Response

Raw card-present API

How do voids and refunds work?

Perform reversals

Carrying out voids

Refunding a transaction