Receive payments with authorization and capture

Separate the authorization and capture to create a charge now, but capture your funds later.

Web
Android
iOS

Receiving one-time card payments under the authorization and capture scheme guarantees the availability of the amount on the customer’s card for a maximum of 30 days. If the payment is not captured in that time, it will be cancelled automatically and the funds will be released.

An example of what you will integrate is as follows:

The flow you will integrate will be as follows:

Flujo auth y captura

1. Obtain one-time payment token

The responsibility of the front-end is to collect the user’s card information in a secure manner, tokenize that information through Kushki’s servers and then send that information to the back-end to initiate the authorization process.

You have two options for integrating: Kajita and Kushki.js.

Kajita

Kushki has payment forms ready to collect card information securely. You will be able to use any of our versions:

  • Cajita: the first version of the payment form. It is not customizable.
  • Kajita: the second version. It allows you to customize your payment forms from your Administration Console and even have several versions of Kajita, for example, one for each payment method.

Create and customize your Kajitas

With Kushki you can create your Kajitas from the Admin Console. Click here to learn how to do it.

Configure Kajita

Include the 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. Do not include the script in a bundle or package or host a copy of it.

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

Add Kajita to your site

Kajita needs a space within your page. Enter the following code in the <body> of your site where you want the payment form to be displayed.

For Kajita (v.2):

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

For Cajita (v.1)

<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, to get the token.

Then, add the script tag.

For Kajita (v.2) you can get the script from your Admin Console as explained here.

<script type="text/javascript">
var kushki = new KushkiCheckout({
kformId: "HmJXukKb5",
form: "my-form",
publicMerchantId: "${publicCfredentialId}",// Replace this with your public credential
amount: {
subtotalIva: 0,
iva: 0,
subtotalIva0: 1000,
}
});
</script>

For v.1 (Cajita), add the following script, making sure that the form has loaded:

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

This will create a predefined form on your page to accept payments.

Kushki.js

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

Configure Kushki.js

Option 1 - CDN

Use the following script tag at the end of the <body> on 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”;
##### Configure the `Kushki` object
Add the following code to your application
```javascript
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, add the form to your payment page with the required fields. You can design it in any way you like.

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="CVV" type="text" name="cvv">
<button id="submit">Pagar $4000</button>
</form>

Then, when the user submits the form, request the token and send it to your back-end.

kushki.requestToken({
amount: '4000',
currency: "MXN",
card: {
name: form.name,
number: form.number,
cvv: 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. Make the authorization

The responsibility of the back-end is to use the collected token to make an authorization request, in case it is approved, make a capture or void depending on the case.

When the user submits the form, your front-end transfers a token to an endpoint you have specified. With this token, you must make a call to our authorization endpoint to initiate the authorization of funds.

  • Javascript
  • Python
  • PHP
import request from 'request';
const options = {
method: 'POST',
url: 'https://api-uat.kushkipagos.com/card/v1/preAuthorization',
headers: {
'content-type': 'application/json'
},
body: {
token: 'QZPnSP1000000b3MG3062555GhIrcYt5', // Replace it with the obtained token
amount: {
subtotalIva: 0,
subtotalIva0: 6000,
ice: 0,
iva: 0,
currency: 'MXN'
},
deferred: {
graceMonths: '02',
creditType: '01',
months: 3
},
orderDetails: {
siteDomain: 'tuebook.com',
shippingDetails: {
name: 'John Doe',
phone: +593988734644,
address: 'Calle 13 Avenida 39 40',
city: 'Guadalajara',
region: 'Jalisco',
country: 'México',
zipCode: 170402
},
billingDetails: {
name: 'John Doe',
phone: +593988734644,
address: 'Calle 13 Avenida 39 40',
city: 'Guadalajara',
region: 'Jalisco',
country: 'México',
zipCode: 170402
}
},
fullResponse: true
},
json: true
};
request(options, (error, response, body) => {
if (error) throw new Error(error);
console.log(body);
});
import requests
url = "https://api-uat.kushkipagos.com/card/v1/preAuthorization"
payload = "{\"token\":\"QZPnSP1000000b3MG3062555GhIrcYt5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":6000,\"ice\":0,\"iva\":0,\"currency\":\"MXN\"},\"deferred\":{\"graceMonths\":\"02\",\"creditType\":\"01\",\"months\":3},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\": \"John Doe\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\":\Guadalajara\",\"region\":\"Jalisco\",\"country\":\"México\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"John Doe Osorio\",\"phone\":\"+593988734644\",\"address\":\"Calle 13 Avenida 39 40\",\"city\":\Guadalajara\",\"region\": \"Jalisco\",\"country\": \"México\",\"zipCode\": \"170402\"}},\"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":"QZPnSP1000000b3MG3062555GhIrcYt5","amount":{"subtotalIva":0,"subtotalIva0":6000,"ice":0,"iva":0,"currency":"MXN"},"deferred":{"graceMonths":"02","creditType":"01","months":3},"orderDetails": {"siteDomain":"tuebook.com","shippingDetails":{"name":"John Doe","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Guadalajara","region":"Jalisco","country":"México","zipCode":"170402"},"billingDetails":{"name": "John Doe","phone":"+593988734644","address":"Calle 13 Avenida 39 40","city": "Guadalajara","region":"Jalisco","country":"México","zipCode": "170402"}},"fullResponse":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/preAuthorization');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

3. Kushki verifies authorization

Kushki will validate the availability of funds with the card issuer. Once the response from Kushki is obtained, save the ticketNumber as it will be the identifier for later capture as well as reversal.

4. Execution of the charge

4.1. Make the capture (Optional)

Capture the amount you define according to the authorized by calling our capture endpoint, using the ticketNumber obtained in the authorization.

  • Javascript
  • Python
  • PHP
var request = require("request");
var options = {
method: 'POST',
url: 'https://api-uat.kushkipagos.com/card/v1/capture',
headers: {'content-type': 'application/json'},
body: {
ticketNumber: '319228478889680318',
amount: {currency: 'MXN', subtotalIva: 0, iva: 0, subtotalIva0: 6000},
fullResponse: true
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
payload = "{\"ticketNumber\":\"319228478889680318\",\"amount\":{\"currency\":\"MXN\",\"subtotalIva\":0,\"iva\":0,\"subtotalIva0\":6000,\"ice\":0},\"fullResponse\":true}"
headers = { 'content-type': "application/json" }
conn.request("POST", "/card/v1/capture", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"ticketNumber":"319228478889680318","amount":{"currency":"MXN","subtotalIva":0,"iva":0,"subtotalIva0":6000,"ice":0},"fullResponse":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/capture');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

4.2 Cancel authorization (Optional)

If you need to cancel an authorization you can do it by calling our charge cancellation enpoint, using the ticketNumber obtained in the authorization.

  • Javascript
  • Python
  • PHP
var request = require("request");
var options = {
method: 'DELETE',
url: 'https://api-uat.kushkipagos.com/v1/charges/1528188291221',
headers: {'content-type': 'application/json'},
body: {
fullResponse: true,
amount: {subtotalIva: 4000, subtotalIva0: 0, ice: 0, iva: 0, currency: 'MXN'}
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
payload = "{\"fullResponse\":true,\"amount\":{\"subtotalIva\":4000,\"subtotalIva0\":0,\"ice\":0,\"iva\":0,\"currency\":\"MXN\"}}"
headers = { 'content-type': "application/json" }
conn.request("DELETE", "/v1/charges/1528188291221", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"fullResponse":true,"amount":{"subtotalIva":4000,"subtotalIva0":0,"ice":0,"iva":0,"currency":"MXN"}}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/v1/charges/1528188291221');
$request->setRequestMethod('DELETE');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Test your integration

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

  • Approved transaction: 5451951574925480
  • Declined transaction on token request (front-end): 4574441215190335
  • Transaction declined on authorization: 4349003000047015
  • Transaction declined on capture: 4547004841271012