Accept a Card Payment

Accept online card payments securely

Web
iOS
Android

Receiving payments with debit and credit cards in your website means capturing the card details, generating a token, and sending the payment to Kushki for processing.

An example of a card payment form would be as shown below:

The payment flow that you will integrate is as shown below:

card payment flow

1. Set up your Front End

The front end is responsible for collecting the user’s card details securely, generating a token for such information through Kushki’s servers, and sending that information to the back end to start the payment process.

You have two options to integrate: Cajita and Kushki.js.

Cajita

Use Cajita to simplify your integration and provide a ready-to-use solution to collect card details safely.

Set up Cajita

Embed kushki-checkout.js script in your payment page by adding it to the <head> of your HTML file. Always load kushki-checkout directly from cdn.kushkipagos.com to ensure that you comply with the PCI standard. Never embed the script in a bundle or package, nor host a copy of it.

<head>
<title>Checkout</title>
<script src="https://cdn.kushkipagos.com/kushki-checkout.js"> </script>
</head>

Add Cajita to your Website

Cajita needs a place to live on your page. Enter the following code in your website’s <body>, where you want the payment form to be displayed.

<form id="payment-form" action="/confirm" method="post">
<input type="hidden" name="cart_id" value="123">
</form>

Remember to configure the action of the action form according to the corresponding endpoint in your back end.

Then, add the following script tag. Make sure that the form has been uploaded.

<script type="text/javascript">
var kushki = new KushkiCheckout({
form: "payment-form",
merchant_id: "8291028192001", // Replace this with your public merchant id
amount: "149900",
currency: "COP",
payment_methods:["credit-card"], // You will be able to add more payment methods
inTestEnvironment: true, // Configured in test mode
});
</script>

This will create a predesigned form on your website to accept payments.

Kushki.js

Use Kushki.js if you need more control over the “look & feel” or appearance of your payment form.

Set up Kushki.js

Option 1 - CDN

Use the following script tag at the end of the <body> of your payment page.

<script src="https://cdn.kushkipagos.com/kushki.min.js"></script>
Option 2 - npm

Install the package from npm.

npm install --save @kushki/js

Then import it into your code using the following code.

import { Kushki } from “@kushki/js”;
Set up Kushki object

Add the following code to your application

const kushki = new Kushki({
merchantId: 'public-merchant-id', // Your public merchant id
inTestEnvironment: true,
});

Collect User Information and Send it to your Back End

First, embed the form in your payment page adding the required fields. You can design it in the way that best suits you.

For example:

<form id="payment-form">
<input placeholder="Card Number" type="text" name="number">
<input placeholder="Full Name" type="text" name="name">
<input placeholder="MM" type="text" name="expiry_month">
<input placeholder="YY" type="text" name="expiry_uear">
<input placeholder="CVC" type="text" name="cvc">
<button id="submit">Pay $149900</button>
</form>

And, for the moment the user submits the form, add the token request and take it to your back end.

kushki.requestToken({
amount: '149900',
currency: "COP",
card: {
name: form.name,
number: form.number,
cvc: form.cvv,
expiryMonth: form.expiry_month,
expiryYear: form.expiry_year,
},
}, (response) => {
if(response.code){
console.log(response);
// Submit your code to your back-end
} else {
console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
}
});

2. Set up your Back End

The back end is responsible for receiving the token obtained from your front end and starting the payment process with Kushki.

When the user submits the form, your front end sends a token to an endpoint that you specified previously. Using this token, you must make a call to our charges endpoint to initiate the charge.

  • Javascript
  • Python
  • PHP
var request = require("request");
var options = {
method: 'POST',
headers: {
'Private-Merchant-Id': 'your-private-merchat-id', // Replace with your Private merchant id
'Content-Type': 'application/json'
},
url: 'https://api-uat.kushkipagos.com/card/v1/charges', // Test environment
body: {
token: "V0OzRB100000xhxQB8035251pHLBQsq5", // Replace with the token you received
amount: {
subtotalIva: 0,
subtotalIva0: 149900,
ice: 0,
iva: 0,
currency: "COP"
},
metadata: {
contractID: "157AB"
},
contactDetails: {
documentType: "CC",
documentNumber: "1009283738",
email: "test@test.com",
firstName: "Diego",
lastName: "Cadena",
phoneNumber: "+5730162826289"
},
orderDetails: {
siteDomain: "tuebook.com",
shippingDetails: {
name: "Diego Cadena",
phone: "+5730162826289",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Medellín",
region: "Antioquia",
country: "Colombia",
zipCode: "170402"
},
billingDetails: {
name: "Diego Osorio",
phone: "+593988734644",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Medellín",
region: "Antioquia",
country: "Colombia",
zipCode: "170402"
}
},
productDetails: {
product: [{
id: "198952AB",
title: "eBook Digital Services",
price: 69900,
sku: "10101042",
quantity: 1
},
{
id: "198953AB",
title: "eBook Virtual Selling",
price: 99900,
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/v1/charges"
payload = "{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":149900,\"ice\":0,\"iva\":0,\"currency\":\"COP\"},\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"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}"
headers = {'Private-Merchant-Id': 'your-private-merchat-id','Content-Type': 'application/json'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":149900,\"ice\":0,\"iva\":0,\"currency\":\"COP\"},\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Osorio\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":69900,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":99900,\"sku\":\"004834GQ\",\"quantity\":1}]},\"fullResponse\":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/charges');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'Private-Merchant-Id: your-private-merchat-id',
'Content-Type: application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

According to the response you obtained, redirect the user to a success or failure page to inform them whether the transaction was approved or declined.

Perform an anti-fraud validation (Optional)

For the security of your business, Kushki’s fraud prevention team will ask you in certain cases or for certain amounts, to activate identity validation when receiving card payments.

How does an Anti-Fraud Validation work?

When you send the charge, Kushki will perform a validation to verify if the document number is associated with the credit card sent in the request. If the validation is successful, the charge will be made automatically, otherwise, we will send you the response so that you decide how to proceed.

Submit card details

The card details will be sent to validation by using the existing charge endpoint. Make sure to set the ignoreWarnings parameter to false, include the type and number of the document, first name, last name, and second last name in the contactDetails object, and set the fullResponse parameter to true. If you decide to skip this validation, set the ignoreWarnings parameter to true value.

  • 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/v1/charges', // Test environment
headers: {
'content-type': 'application/json'
},
body: {
{
"token": "V0OzRB100000xhxQB8035251pHLBQsq5",
"amount": {
"subtotalIva": 0,
"subtotalIva0": 160980,
"ice": 0,
"iva": 0,
"currency": "COP"
},
"ignoreWarnings":false,
"metadata": {
"contractID": "157AB"
},
"contactDetails": {
"documentType": "CC",
"documentNumber": "1009283738",
"email": "test@test.com",
"firstName": "Diego",
"lastName": "Osorio",
"secondlastName": "Valdivia",
"phoneNumber": "+593988734644"
},
"orderDetails": {
"siteDomain": "tuebook.com",
"shippingDetails": {
"name": "Diego Osorio",
"phone": "+593988734644",
"address": "Eloy Alfaro 139",
"city": "Bogotá",
"region": "Cundinamarca",
"country": "Colombia",
"zipCode": "170402"
},
"billingDetails": {
"name": "Diego Osorio",
"phone": "+593988734644",
"address": "Eloy Alfaro 139",
"city": "Bogotá",
"region": "Cundinamarca",
"country": "Colombia",
"zipCode": "170402"
}
},
"productDetails": {
"product": [{
"id": "198952AB",
"title": "eBook Digital Services",
"price": 69900,
"sku": "10101042",
"quantity": 1
},
{
"id": "198953AB",
"title": "eBook Virtual Selling",
"price": 9990,
"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/v1/charges"
payload = "{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":160980,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"secondlastName\":\"Valdivia\"\"phoneNumber\":\"+593988734644\"}
\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"secondlastName\":\"Valdivia\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Bogotá\",\"region\":\"Cundinamarca\",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Bogotá\",\"region\":\"Cundinamarca\",\"country\":\"Colombia\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":69900,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9900,\"sku\":\"004834GQ\",\"quantity\":1}]},\"fullResponse\":true}"
headers = {'content-type': 'application/json'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":160980,\"ice\":0,\"iva\":0,\"currency\":\"COP\"},\"ignoreWarnings\":false,\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"secondlastName\":\"Valdivia\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Osorio\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Bogotá\",\"region\":\"Cundinamarca\",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Bogotá\",\"region\":\"Cundinamarca\",\"country\":\"Colombia\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":6990000,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9990,\"sku\":\"004834GQ\",\"quantity\":1}]},\"fullResponse\":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/charges');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Receiving the Validation Result

The response to identity validation will be received in the rules object, and there are three possible responses:

ResponseParameters ReceivedWhat to do?
Approved Transation{"code": "000","message": "TransUnion Approval"}No further action will be necessary, the transaction will be sent to the processor and according to the response, it redirects the user to a success or failure page to inform the customer whether the transaction was approved or declined.
Failed Transaction:(Validation was not possible){"code": "006","message": "TransUnion Unavailable"}Verify that the parameters documentNumber and documentType have been sent in the object contactDetails and try again.
Failed Transaction:(The validation was performed and the result was negative){"code": "322","message": "TransUnion Declined"}In case the transaction has been declined by the validation system, you will have two options: 1)Ignore the warning and continue with the payment: In this case, you should go back to the previous step, ensuring that you set the ignoreWarnings parameter to true and the same token already generated 2)Acknowledge the warning and reject the transaction.

3. Test your Integration

You can use some test cards in test mode to ensure that your integration is ready. Use them adding any CVC, zip code, and a future expiration date.

  • Approved transaction: 5451951574925480
  • Transaction declined during token request (front end): 4574441215190335
  • Transaction declined during charge request (back end): 4349003000047015

If you wish to test a card payment by performing an anti-fraud validation, send the card numbers below when requesting the token and when making the charge request, send the document number and document type indicated within the contactDetails object:

Approved validation:

  • Credit card: 5642569816497595
  • Document number: 80004393
  • Document type: CC

Rejected validation:

  • Credit card: 5642569816497595
  • Document number: 8000000
  • Document type: CC

Validation not performed:

  • Do not send documentNumber, nor documentType in the contactDetails object.

4. Prepare your Certification

Read the following guidelines for technical certification approval (required to obtain productive account credentials):

  • Tax calculations must be correct.
  • Sensitive card details are not stored in your database (full card number, CVV, etc.).
  • Messages displayed on the screen are in line with Kushki’s responses.
  • All Kushki responses must be saved and recorded (required in case you need support).
  • Make sure to send all the required data specified in the API Reference, such as product details (productDetails), as well as your customer-payer contact details (contactDetails), along with billing ( "orderDetails". "billingDetails") and shipping details (if your business model requires it: "orderDetails". "shippingDetails"), within the request to make the charge.
  • Kushki’s logo must be visible for the customer. You can find our logo in several formats here.

If you are using Kushki.js, also check the following:

  • The cardholder’s name must be required.
  • The card number field must be required.
  • The card number field must only accept numbers.
  • The credit card field must allow a maximum of 16 digits (there may be less).
  • The CVV field must be required.
  • The CVV field must accept only numbers.
  • The CVV field must be of password type.
  • The CVV field must allow no more than 4 digits and no less than 3 digits.
  • The expiration date must be required.
  • The expiration date must accept only future dates.
  • The payment button must be disabled after the first click.
  • If you have enabled the option of email notification to your customers about the transaction result from Kushki, the email parameter of the object contactDetails is required.
  • Kushki’s logo must be visible for the customer. You can find our logo in several formats here.

Accept payments with OTP

Only Web. OTP (One Time Password) is an extra layer of protection against online fraud.

Accept Webhooks

Manage correctly post-payment events.