Direct charge (without token) 🅱️

May 29, 2024

This functionality is available for the following models:

☑ Acquirer
☐ Aggregator

To learn about which types of cards are enabled for each of the affiliation models, please refer to our guide of supported card brands.

Receiving direct payments with debit and credit cards on your site involves capturing the card information and sending the payment to Kushki for processing. This integration method is simpler because there is no need to request a token and then a charge to process a direct charge or a pre-authorization; you just need to use a single direct charge service.

Limitations

Available only with Kushki acquiring in Chile 🇨🇱, Colombia 🇨🇴, Mexico 🇲🇽, and Peru 🇵🇪.
Only supports single charges and pre-authorizations with Visa and Mastercard.
Not compatible with Sift Science or TransUnion anti-fraud tools.
Not compatible with Kushki’s 3DS authentication (you can use your own anti-fraud authentication engine instead).
Not compatible with Kushki’s OTP authentication.

The payment flow you will integrate is as follows:

cargo directo en

Simple Charge

To perform a simple card charge, you will need to use the card and customer data to make a call to our non-token payment endpoint to initiate the charge.

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();

Deferred Charges

To perform a deferred charge, you must send the number of months to defer the payment in the months parameter as part of the charge request. If needed, you can refer to the deferred request method to check if deferred payment options are available for the BIN of the card entered by the user.

As a response to this call, you will receive the type, the available months, and the grace months (skip payments), as shown in the following sample response. To execute the charge, you only need to use the months parameter.

[
   {
      "months":[
         "2",
         "3",
         "4",
         "5",
         "6",
         "7",
         "8",
         "9",
         "10",
         "11",
         "12"

      ],
      "monthsOfGrace":[

      ],
      "type":"all"
   }
]

And here’s how you should send the months object in a charge:

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

External 3DS Authentication

If you have your own 3DS authentication engine, include the threeDomainSecure object in your request.

Depending on the brand, the fields to send may vary:

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

The eci (Electronic Commerce Indicator) field allows the following values:

Visa:

eci: 05 y 06 represent secure transactions.
eci: 07 represents risky transactions. To process risky transactions, set the acceptRisk field to true.

Mastercard:

eci: 01 and 02 represent secure transactions.
eci: 00 represents risky transactions. To process risky transactions, set the acceptRisk field to true.

Here is an example of a charge that includes the object: 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
  }
}

Process external subscriptions with Kushki

With Kushki, you can process charges if you have your own subscription engine. There are two options for this:

Option 1. Without sending CVV

Request Kushki to activate the service on your account.
Send the charge without CVV. Make sure to include the externalSubscriptionID field with the ID of the subscription from your external engine, with a length of 20 or fewer alphanumeric characters. This way, Kushki will recognize it as a subscription managed by an external engine.

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

Option 2. Sending CVV in the initial transaction

Send initialRecurrence in the transactionMode parameter and process the charge. For this initial transaction, make sure to send the 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"
}

Ensure you save the transactionReference from the completed charge in the previous step.
For subsequent transactions without CVV, send subsequentRecurrence in the transactionMode parameter, and make sure to include the transactionReference in the initialRecurrenceReference field.

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

Test your integration.

There are test cards you can use in the UAT environment to ensure your integration is ready. Use them with any CVV, postal code, and future expiration date.

Approved transaction: 5451951574925480
Declined transaction at token request (front-end): 4574441215190335
Declined transaction at charge request (back-end): 4349003000047015