Acepta pagos

Acepta pagos con una terminal POS certificada desde tu punto de venta a través de Raw card-present API. Con Raw card-present API puedes usar y administrar tus propias terminales, conectándote a nuestra red de pagos para procesar transacciones. Debes generar y administrar de forma segura las claves criptográficas que te permitirán cifrar la información leída de la tarjeta a través de las terminales. Envía la información requerida en la solicitud para realizar una operación exitosa a través de nuestra API.

Modelo de datos de la solicitud

Estos son todos los parámetros que puedes configurar al momento de realizar una solicitud.

PropiedadTipoRequeridoDescripciónValores permitidos
amountObjectMonto total de la transacción (incluyendo propina e impuestos).
amount.currencyStringMoneda de la transacción.MXN, COP, USD, CLP, PEN
amount.ivaNumberMonto del impuesto al valor agregado de la transacción.
amount.subtotal_ivaNumberMonto de la transacción sin incluir impuestos.
amount.subtotal_iva0NumberEn caso de que la transacción no tenga impuestos, coloca el monto total en esta propiedad.
amount.tipNumberNoMonto opcional para agregar propina a la transacción.
amount.extra_taxesObjectNoObjeto con propiedades adicionales de impuestos para ciertos giros comerciales.
amount.extra_taxes.airport_taxNumberNoimpuesto aeroportuario.
amount.extra_taxes.iacNumberNoImpuesto agregado al consumo.
amount.extra_taxes.iceNumberNoImpuesto a consumos especiales.
amount.extra_taxes.travel_agencyNumberNoUsado en aerolíneas.
cardObjectNoObjeto con información de la tarjeta.
card.card_holder_nameStringNoNombre del tarjetahabiente.
card_detailsObjectObjeto con información de la tarjeta.
card_details.enc_tlvStringNoRequerido si la lectura de la tarjeta es por chip. Contiene información cifrada del chip EMV de la tarjeta.
card_details.pin_blockStringNoBloque de datos que encapsulan el número de identificación personal (PIN) durante el proceso.
card_details.pin_ksnStringNoRequerido si se envía la propiedad pin_block. Es requerido en el proceso DUKPT para identificar la clave inicial usada para cifrar la información del PIN.
card_details.pin_ksn_descStringNoPin descriptor.
card_details.reading_typeStringIndica el tipo de lectura de la tarjeta.
  • ICC : Lectura por chip.
  • MCR: Lectura por banda magnética.
  • NFC: Lectura sin contacto (Contactless).
ICC, MCR, NFC
card_details.tracksObjectObjeto con información leída de la tarjeta.
card_details.tracks.enc_track1StringNoRequerido cuando la lectura es por banda magnética (MCR). Información cifrada contenida en la tarjeta.
card_details.tracks.enc_track2StringNoRequerido cuando la lectura es por chip (ICC), banda magnética (MCR) o sin contacto (NFC). Información cifrada contenida en la tarjeta.
card_details.tracks.track_ksnStringRequerido cuando la lectura es por chip (ICC) o sin contacto (NFC). Clave de cifrado de datos.
card_details.tracks.track_ksn_descStringNoRequerido cuando se envía la propiedad track_ksn. KSN descriptor.
card_details.tracks.track2_lengthStringNoRepresentación de la longitud de enc_track2.
client_transaction_idStringIdentificador único por transacción generado de tu lado. UUID v4.
countryStringPaís de la transacción (ISO 3166-1 alpha-3).COL, MEX, CHL, PER
is_deferredBooleanNoEstablece una transacción como diferida.
deferredObjectNoRequerido cuando se envía la propiedad is_deferred como true. Objeto con la configuración de diferidos de la transacción.
deferred.monthsStringNoCantidad de cuotas a diferir la transacción.
is_cashbackBooleanNoEstablece si se realizará retiro de efectivo durante una transacción.
cashback_amountNumberNoRequerido cuando se envía la propiedad is_cashback. Establece el monto del efectivo a retirar durante una transacción.
pos_detailsObjectObjeto con información sobre la terminal.
pos_details.brandStringEnvía la marca de la terminal. Por ejemplo, Sunmi.
pos_details.has_printBooleanNoIndica si la terminal cuenta con impresora integrada.
pos_details.locationObjectNoObjeto con información sobre la ubicación de la terminal.
pos_details.location.latitudeNumberNoEstablece la latitud desde donde se origina la transacción.
pos_details.location.longitudeNumberNoEstablece la longitud desde donde se origina la transacción.
pos_details.modelStringNoModelo de la terminal.
pos_details.terminal_idStringNoId de la terminal generado de tu lado.
pos_details.versionStringNoVersión del software de la terminal.
contact_detailsObjectObjeto con información del cliente.
contact_details.document_numberStringNoNúmero de documento de identificación del cliente.
contact_details.document_typeStringTipo de documento de identificación.
contact_details.emailStringNoCorreo electrónico del cliente.
contact_details.first_nameStringNoNombre del cliente.
contact_details.last_nameStringNoApellido del cliente.
contact_details.second_last_nameStringNoSegundo apellido (aplica solo para Colombia).
contact_details.phone_numberStringNoNúmero de teléfono del cliente.
transaction_modeStringEstablece el modo de operación.Authorization, Reverse, Void
transaction_typeStringEstablece el tipo de operación.capture, charge, preAuth, reAuthorization, tip, refund
cvm_typeStringMétodo de verificación del titular de la tarjeta.
  • none : Sin método de verificación.
  • pin: Método de verificación por pin.
  • signature: Método de verificación por firma.
none, pin, signature
sub_merchantObjectNoObjeto con información del comercio.
sub_merchant.mccStringNoCódigo de categoría del comercio.
sub_merchant.id_affiliationStringNoId de afiliación del comercio.
sub_merchant.soft_descriptorStringNoTexto que aparecerá en el extracto del tarjetahabiente. Es útil para ayudar a los clientes a identificar las compras y evitar cargos no reconocidos.
sub_merchant.cityStringNoCiudad del comercio.
sub_merchant.city_codeStringNoCódigo de ciudad (ISO 3166-2) del comercio. Requerido solo para México.
sub_merchant.country_ansStringNoISO 3166-1 alpha-3.
sub_merchant.zip_codeStringNoCódigo postal del comercio.
sub_merchant.addressStringNoDirección del comercio.
sub_merchant.social_reasonStringNoRazón social del comercio. Aplica solo para transacciones Visa.
sub_merchant.codeStringNoId del subcomercio.
merchant_idStringNoId del comercio.
omit_cardBooleanNoEstablece una operación sin tarjeta. Disponible solo en Chile.
metadataObjectNoObjeto para incluir información adicional por parte del comercio.

Operaciones

Descubre todas las operaciones disponibles a través de integraciones por Raw card-present API.

Venta

Realiza una venta presente con tarjetas físicas o digitales en tu comercio a través de una terminal. La terminal te permite leer la tarjeta de tu cliente y realizar operaciones implicadas en el proceso DUKPT. La responsabilidad de tu sistema punto de venta es enviar los datos leídos de la terminal hacia a Kushki para su procesamiento.

Para realizar una venta, consume el endpoint Single payment, establece el modo de transacción (transaction_mode) como Authorization, el tipo de transacción (transaction_type) como charge y envía la demás información requerida.

Ejemplo de una solicitud

{
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "charge",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Cashback

Para realizar una venta con retiro de efectivo, consume el endpoint Single payment, establece el modo de transacción y el tipo de transacción igual que en la venta, establece la propiedad is_cashback como true y establece el monto del efectivo a retirar durante la transacción en la propiedad cashback_amount.

Ejemplo de una solicitud

{
"is_cashback": true,
"cashback_amount": 1000,
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "charge",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Pre-propina

Para realizar una venta con propina, consume el endpoint Single payment, establece el modo de transacción y el tipo de transacción igual que en la venta y establece el monto de la propina en la propiedad tip dentro del objeto amount.

Ejemplo de una solicitud

{
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"tip": 100,
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "charge",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Para más información de cómo enviar la propina en una transacción, consulta nuestra sección de preguntas frecuentes.

Pagos diferidos

Para realizar una venta diferida, consume el endpoint Single payment, establece el modo de transacción y el tipo de transacción igual que en la venta, establece la propiedad is_deferred como true y establece el número de cuotas a diferir un pago en la propiedad months dentro del objeto deferred.

Ejemplo de una solicitud

{
"is_deferred": true,
"deferred": {
"months": "12"
},
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "charge",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Reserva de saldo (pre-authorization)

En caso de que requieras reservar un importe de la tarjeta de tu cliente, podrás utilizar el servicio de preautorización. Por ejemplo, cuando tu comercio requiera solicitar un depósito para tener la garantía de que el costo total se financiará al final del servicio, podrás retener una cantidad específica de la cuenta bancaria de tu cliente.

Para realizar una reserva de saldo, consume el endpoint Authorization and capture, establece el modo de transacción (transaction_mode) como Authorization, el tipo de transacción (transaction_type) como preAuth y envía la demás información requerida.

Ejemplo de una solicitud

{
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "preAuth",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Reautorización (reauthorization)

En caso de que requieras modificar el importe de una reserva de saldo previamente realizada o extender la fecha de la captura, podrás utilizar el servicio de reautorización. Envía un monto igual a $0 en una reutorización para extender el plazo de la captura o envía un monto en la reautorización para extender la reserva de saldo.

Para realizar una reautorización, consume el endpoint Authorization and capture, establece el modo de transacción (transaction_mode) como Authorization, el tipo de transacción (transaction_type) como reAuthorization y envía la demás información requerida.

Ejemplo de una solicitud

{
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "reAuthorization",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Captura (Capture)

Una vez que soliciten a tu comercio cobrar los fondos de la tarjeta de tu cliente, puedes capturar el monto del producto o servicio adquirido.

La captura solicitada corresponde a la suma de la autorización y todas las reautorizaciones realizadas que no hayan sido canceladas.

Al recibir pagos bajo el esquema de autorización y captura, tu comercio puede garantizar la disponibilidad del monto en la tarjeta de tu cliente máximo por 28 días para tarjetas de crédito y 7 días para tarjetas de débito. Si el pago de la transacción no se captura durante los tiempos mencionados anteriormente, los fondos retenidos serán liberados por el banco emisor de nuevo al tarjetahabiente.

Para realizar una captura, consume el endpoint Authorization and capture, establece el modo de transacción (transaction_mode) como Authorization, el tipo de transacción (transaction_type) como capture y añade la propiedad transaction_reference con el valor de la referencia devuelta al momento de realizar una Reserva de saldo (pre-authorization).

Ejemplo de una solicitud

{
"transaction_reference": "d5979f96-0449-414b-9ece-b0b3681089d6"
"card": {
"card_holder_name": "John Doe"
},
"amount": {
"iva": 0,
"currency": "CLP",
"subtotal_iva": 0,
"subtotal_iva0": 60000
},
"country": "CLP",
"cvm_type": "none",
"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": "Authorization",
"transaction_type": "capture",
"client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}

Respuesta

Si la información enviada es correcta, obtendrás una respuesta similar a la siguiente con la información de la transacción procesada.

{
"F11": "101619",
"cvm_type": "none",
"franchise": "MASTERCARD",
"message_fields": {
"F38": "121866",
"F39": "00"
},
"kushki_response": {
"code": "000",
"message": "Transacción Aprobada."
},
"transaction_type": "charge",
"authorized_amount": 611,
"additional_amounts": {
"amount": 0,
"card_type": "",
"amount_type": "",
"account_type": "",
"currency_code": ""
},
"transaction_status": "APPROVAL",
"transaction_reference": "fb1d8f34-31fc-4d9d-ab7e-375d7f0801a5"
}

En caso de algún error, podrás obtener alguna respuesta con una estructura similar a la siguiente:

{
"code": "E001",
"details": {
"Origin": "Process Generic Transaction | validateRequest",
"Message": "document_number: cannot be blank; document_type: cannot be blank."
},
"message": "Cuerpo de la petición inválido."
}

Consulta la lista completa de códigos de error.

Revisa la referencia de Raw card-present API para más información.


Datos de prueba
Realiza los ajustes necesarios en tu sistema con los datos de prueba.
Transacciones
Obtén la lista de transacciones con información relevante para tus operaciones.