Receive payments with authorization and capture

March 04, 2024

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

Web

iOS

Android

This functionality is available for the following models:

☑ Acquirer
☐ Aggregator

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 9 days. If the payment is not captured in that time, held funds may be released by the issuing bank back to the cardholder.

An example of what you will integrate is as follows:

The flow you will integrate will be as follows:

Flujo auth y captura EN

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: 6000,
     }
    });
</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: "6000",
        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 $6000</button>
</form>

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

kushki.requestToken({
  amount: '6000',
  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'
        },
        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-issuing entity. Once you receive a response from Kushki, save the ticketNumber, as this will be the identifier for the reauthorization, capture or cancellation.

4. Reauthorize the charge (optional)

Extend the validity or amount of the authorization before capturing your funds by calling our reauthorization endpoint.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api-uat.kushkipagos.com/card/v1/reauthorization',
  headers: {'content-type': 'application/json' , 'Private-Merchant-Id': '13dc47c55c714839800a22824d56126c'
},
  body: {
    ticketNumber: '319228478889680318',
    amount: {currency: 'MXN', subtotalIva: 0, iva: 0, subtotalIva0: 6000},
    fullResponse: v2
  },
  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/reauthorization"

payload = {
    "ticketNumber": "319228478889680319",
    "amount": {
        "currency": "MXN",
        "subtotalIva": 0,
        "iva": 0,
        "subtotalIva0": 6000,
        "ice": 0
    },
    "fullResponse": "v2"
}
headers = {
    "Content-Type": "application/json",
    "Private-Merchant-Id": "13dc47c55c714839800a22824d56126c"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

$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":v2}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/reauthorization');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'content-type' => 'application/json'
 ' Private-Merchant-Id ' => '13dc47c55c714839800a22824d56126c'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

5. Execution of the charge

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

5.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\":6000,\"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":6000,"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