Cargo directo (sin token) 🅱️

09 enero 2025

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente
☐ Agregador

Para conocer los tipos de tarjeta habilitados en cada uno de los modelos de afiliación, por favor consulta nuestra guía de marcas de tarjeta soportados.

Recibir pagos directos con tarjetas de débito y crédito en tu sitio consiste en capturar la información de la tarjeta y enviar el pago a Kushki para ser procesado. Esta forma de integración es más simple, ya que no es necesario solicitar un token y luego un charge para procesar un cargo directo o una preautorización, sino que basta con consumir un solo servicio de cargo directo.

Limitaciones

Solo está disponible con adquirencia Kushki en Chile 🇨🇱, Colombia 🇨🇴, México 🇲🇽 y Perú 🇵🇪.
Solo disponible para cargos únicos y preautorizaciones con tarjetas Visa y Mastercard.

Soporta ✅	No soporta ❌
- Pagos únicos con tarjeta de débito y crédito - Cargos recurrentes de Kushki -Pagos diferidos (Meses sin intereses) - Autorización y captura	- Integración con librerías de Front (Kushki.js, Android, iOS -Autenticación OTP y 3DS de Kushki(en su lugar podrás usar tu propio motor de autenticación antifraude) -Motor antifraude Siftscience

El flujo de pago que integrarás es el siguiente:

cargo directo es

Cargo simple

Para realizar un cargo simple con tarjeta, deberás usar los datos de la tarjeta y de tu cliente para realizar una llamada a nuestro endpoint de pagos sin token para iniciar el cobro.

Javascript
Python
PHP

var request = require("request");

var options = {
        method: 'POST',
        headers: [
            'Private-Merchant-Id': '' // Replace with your Private merchant id
        ]
        url: 'https://api-uat.kushkipagos.com/card/v2/charges', // Test environment
        headers: {
            'content-type': 'application/json'
        },
        body: {
            {
   "card":{
      "name":"John Doe",
      "number":"5311220000122112",
      "expiryMonth":"12",
      "expiryYear":"25",
      "cvv":"123"
   },
   "amount":{
      "subtotalIva":0,
      "subtotalIva0":16.98,
      "ice":0,
      "iva":0,
      "currency":"USD"
   },
   "metadata":{
      "contractID":"157AB"
   },
   "contactDetails":{
      "documentType":"CC",
      "documentNumber":"1009283738",
      "email":"test@test.com",
      "firstName":"Diego",
      "lastName":"Cadena",
      "phoneNumber":"+593988734644"
   },
   "orderDetails":{
      "siteDomain":"tuebook.com",
      "shippingDetails":{
         "name":"Diego Cadena",
         "phone":"+593988734644",
         "address":"Eloy Alfaro 139 y Catalina Aldaz",
         "city":"Quito",
         "region":"Pichincha",
         "country":"Ecuador",
         "zipCode":"170402"
      },
      "billingDetails":{
         "name":"Diego Cadena",
         "phone":"+593988734644",
         "address":"Eloy Alfaro 139 y Catalina Aldaz",
         "city":"Quito",
         "region":"Pichincha",
         "country":"Ecuador",
         "zipCode":"170402"
      }
   },
   "productDetails":{
      "product":[
         {
            "id":"198952AB",
            "title":"eBook Digital Services",
            "price":6990000,
            "sku":"10101042",
            "quantity":1
         },
         {
            "id":"198953AB",
            "title":"eBook Virtual Selling",
            "price":9990000,
            "sku":"004834GQ",
            "quantity":1
         }
      ]
   }
}
                "fullResponse": true
            },
            json: true
        };

        request(options, function(error, response, body) {
            if (error) throw new Error(error);

            console.log(body);
        });

import requests

url = "https://api-uat.kushkipagos.com/card/v2/charges"

payload = "{\n \"card\": {\n \"name\": \"John Doe\",\n \"number\": \"5311220000122112\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvv\": \"123\"\n },\n \"amount\": {\n \"subtotalIva\": 0,\n \"subtotalIva0\": 5000,\n \"ice\": 0,\n \"iva\": 0,\n \"currency\": \"MXN\",\n \"isDeferred\": false\n },\n \"metadata\": {\n \"Referencia\": \"99999\"\n },\n \"contactDetails\": {\n \"documentType\": \"CC\",\n \"documentNumber\": \"1234567890\",\n \"email\": \"user@example.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"phoneNumber\": \"+593912345678\"\n },\n \"orderDetails\": {\n \"siteDomain\": \"example.com\",\n \"shippingDetails\": {\n \"name\": \"John Doe\",\n \"phone\": \"+593912345686\",\n \"address1\": \"Eloy Alfaro 139 y Catalina Aldaz\",\n \"address2\": \"centro 123\",\n \"city\": \"Quito\",\n \"region\": \"Pichincha\",\n \"country\": \"Ecuador\"\n },\n \"billingDetails\": {\n \"name\": \"John Doe\",\n \"phone\": \"+593912345686\",\n \"address1\": \"Eloy Alfaro 139 y Catalina Aldaz\",\n \"address2\": \"centro 123\",\n \"city\": \"Quito\",\n \"region\": \"Pichincha\",\n \"country\": \"Ecuador\"\n }\n },\n \"productDetails\": {\n \"product\": [\n {\n \"id\": \"198952AB\",\n \"title\": \"eBook Digital Services\",\n \"price\": 10000,\n \"sku\": \"10101042\",\n \"quantity\": 1\n }\n ]\n },\n \"citMit\": \"C101\",\n \"fullResponse\": \"v2\"\n}"
headers = {'content-type': 'application/json'}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

$client  =  new  \GuzzleHttp\Client();
$response  =  $client->request('POST',  'https://api-uat.kushkipagos.com/card/v2/charges',  [
'body'  =>  '{
"card": {
"name": "John Doe",
"number": "5311220000122112",
"expiryMonth": "12",
"expiryYear": "25",
"cvv": "123"
},
"amount": {
"subtotalIva": 0,
"subtotalIva0": 5000,
"ice": 0,
"iva": 0,
"currency": "MXN",
"isDeferred": false
},
"metadata": {
"Referencia": "99999"
},
"contactDetails": {
"documentType": "CC",
"documentNumber": "1234567890",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+593912345678"
},
"orderDetails": {
"siteDomain": "example.com",
"shippingDetails": {
"name": "John Doe",
"phone": "+593912345686",
"address1": "Eloy Alfaro 139 y Catalina Aldaz",
"address2": "centro 123",
"city": "Quito",
"region": "Pichincha",
"country": "Ecuador"
},
"billingDetails": {
"name": "John Doe",
"phone": "+593912345686",
"address1": "Eloy Alfaro 139 y Catalina Aldaz",
"address2": "centro 123",
"city": "Quito",
"region": "Pichincha",
"country": "Ecuador"
}
},
"productDetails": {
"product": [
{
"id": "198952AB",
"title": "eBook Digital Services",
"price": 10000,
"sku": "10101042",
"quantity": 1
}
]
},
"citMit": "C101",
"fullResponse": "v2"
}',
'headers'  =>  [
'Accept'  =>  'application/json',
'Content-Type'  =>  'application/json',
'Private-Merchant-Id'  =>  '',
],
]);
echo  $response->getBody();

Cargos diferidos

Si se quiere hacer pago con opción de diferidos, asegúrate de enviar el objeto deferred con los parámetros meses de gracia, meses y tipo de crédito (recibidos al consultar los diferidos para un BIN). Como respuesta a esta llamada, recibirás el nombre del diferido , el tipo type (corresponde al creditType al ejecutar el cargo), los meses disponibles y los meses de gracia (skip payments), tal como se muestra en el siguiente ejemplo de respuesta. Esta es la información que deberás usar al ejecutar el cargo:

[
   {
      "months":[
         "3",
         "6",
         "9",
         "12"
      ],
      "monthsOfGrace":[
         "2"
      ],
      "name":"Diferido con meses de gracia sin intereses",
      "type":"05"
   }
]

Y así deberás enviar el objeto deferred en un cargo:

{
  "card": {
    "name": "John Doe",
    "number": "5311220000122112",
    "expiryMonth": "12",
    "expiryYear": "25",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "ice": 0,
    "iva": 0,
    "currency": "USD",
    "isDeferred": true,
    "deferred": {
      "graceMonths": "02",
      "creditType": "01",
      "months": 3
    }
  },
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      }
    ]
  },
  "fullResponse": "v2"
}

Autenticación 3DS externa

En caso de que cuentes con tu propio motor de autenticación 3DS, incluye el objeto threeDomainSecure en tu solicitud.

Dependiendo de la marca, los campos a enviar varían:

Visa	Mastercard
`cavv`	`directoryServerTransactionID`
`eci`	`eci`
`xid`	`ucaf`
`specificationVersion`	`specificationVersion`
`Cell`	`collectionIndicator`

El campo eci (Electronic Commerce Indicator) permite los siguientes valores:

Visa:

eci: 05 y 06 representa transacciones seguras.
eci: 07 representa transacciones riesgosas. Para procesar transacciones riesgosas, envía el campo acceptRisk en true.

Mastercard:

eci: 01 and 02 representa transacciones seguras.
eci: 00 representa transacciones riesgosas. Para procesar transacciones riesgosas, envía el campo acceptRisk en true.

A continuación un ejemplo de un cargo incluyendo el objeto threeDomainSecure:


{
  "card": {
    "name": "John Doe",
    "number": "5311220000122112",
    "expiryMonth": "12",
    "expiryYear": "25",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 5000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN",
    "isDeferred": false
  },
  "fullResponse": "v2",
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      }
    ]
  },
  "threeDomainSecure": {
    "cavv": "AAABBoVBaZKAR3BkdkFpELpWIiE=",
    "eci": "07",
    "xid": "NEpab1F1MEdtaWJ2bEY3ckYxQzE=",
    "specificationVersion": "2.2.0",
    "acceptRisk": false
  }
}

Procesa suscripciones externas a Kushki

Con Kushki, puedes cursar cobros si tienes tu propio motor de suscripciones. Para ello hay 2 opciones:

Opción 1. Sin envío de CVV

Solicita a Kushki la activación del servicio en tu cuenta.
Envía el cargo cin CVV. Asegúrate de enviar el campo externalSubscriptionID con el id de la suscripción de tu motor externo con una longitud igual o menor a 20 caracteres alfanuméricos, de esta forma Kushki identificará que corresponde a una subscripción administrada por un motor externo.

{
  "card": {
    "name": "John Doe",
    "number": "5311220000122112",
    "expiryMonth": "12",
    "expiryYear": "25",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 5000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN",
    "isDeferred": false
  },
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      }
    ]
  },
  "externalSubscriptionID": "662829373638",
  "fullResponse": "v2"
}

Opción 2. Envíando el cvv en la transacción inicial

Envía initialRecurrence en el parámetro transactionMode y procesa el cargo. Para esta transacción inicial desde enviar el cvv.

{
  "card": {
    "name": "John Doe",
    "number": "5311220000122112",
    "expiryMonth": "12",
    "expiryYear": "25",
    "cvv": "123"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 5000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN",
    "isDeferred": false
  },
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      }
    ]
  },
  "citMit": "C101",
  "transactionMode": "initialRecurrence",
  "fullResponse": "v2"
}

Asegúrate de guardar el transactionReference del cargo completado en el paso anterior.
Para las transacciones posteriores sin cvv, envía subsequentRecurrence en el parámetro transactionMode y asegúrate de incluir el transactionReference el el campo initialRecurrenceReference.

{
  "card": {
    "name": "John Doe",
    "number": "5311220000122112",
    "expiryMonth": "12",
    "expiryYear": "25"
  },
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 5000,
    "ice": 0,
    "iva": 0,
    "currency": "MXN",
    "isDeferred": false
  },
  "metadata": {
    "Referencia": "99999"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+593912345678"
  },
  "orderDetails": {
    "siteDomain": "example.com",
    "shippingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    },
    "billingDetails": {
      "name": "John Doe",
      "phone": "+593912345686",
      "address1": "Eloy Alfaro 139 y Catalina Aldaz",
      "address2": "centro 123",
      "city": "Quito",
      "region": "Pichincha",
      "country": "Ecuador"
    }
  },
  "productDetails": {
    "product": [
      {
        "id": "198952AB",
        "title": "eBook Digital Services",
        "price": 10000,
        "sku": "10101042",
        "quantity": 1
      }
    ]
  },
  "transactionMode": "subsequentRecurrence",
  "initialRecurrenceReference": "c76e2057-fe15-4f90-990c-5d35d130f018",
  "fullResponse": "v2"
}

Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en el ambiente UAT para asegurarte de que tu integración está lista. Úsalas con cualquier CVV, código postal y fecha de expiración futura.

Transacción aprobada: 5451951574925480
Transacción declinada en solicitud de token (front-end): 4574441215190335
Transacción declinada en solicitud de cobro (back-end): 4349003000047015