Reserve Funds in a Card

February 09, 2023

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

Web

iOS

Android

Reserving funds on a one-time use card allows you to authorize the availability of funds for a card, but delay the capture of funds for when the service is completed. For example, a hotel can authorize a payment prior to the arrival of the passenger, and then capture the funds upon departure and completion of the service. It also allows changing the amount of the original authorization in case the order changes due to the shipment, taxes or tipping.

When a payment is authorized, the bank guarantees the availability of the amount and will retain it in the customer’s card for 7 days. If the payment is not captured within that time, it will be automatically cancelled and the funds will be released.

An example of what you will integrate is shown below:

How does it work?

You can reserve funds from a one-time use card. To do so, you should:

Obtain a one-time payment token.
Start a pre-authorization with Kushki.
Kushki will attempt pre-authorization with the card’s issuing entity.
If the response is positive, the merchant will be able to choose between 2 options to be executed before the authorization deadline expires:

Capture an amount: In the event that a charge is to be made on the customer’s card.
Cancel authorization: In the event that the authorization is to be cancelled and the funds on the card are to be released.

The flow that you will integrate is shown below:

Flujo auth y captura EN

1. Obtain a one-time payment token

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 authorization process.

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

Kajita

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

Cajita: our first version of the payment form. Not customizable.
Kajita: is the second version, which allows you to add customizations from your [Administration Console] (https://uat-console.kushkipagos.com/auth) and even have several versions of Kajita, one for each payment method, for example.

Create and customize your Kajitas

Kushki allows you to create your Kajitas from the Administration Console. Click here to learn how to create and customize a Kajita.

Set up 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 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.

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 obtain the token.

Then, add the script tag.

For the Kajita (v.2) You can obtain this script from your [Administration Console] (https://uat-console.kushkipagos.com/auth) as explained here.

<script type="text/javascript">
var kushki = new KushkiCheckout({
    kformId: "HmJXukKb5",
    form: "my-form",
    publicMerchantId: "${publicCfredentialId}",// Reemplaza esto por tucredencial pública
    amount: {
     subtotalIva: 0,
     iva: 0,
     subtotalIva0: 1000,
     }
    });
</script>

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

<script type="text/javascript">
    var kushki = new KushkiCheckout({
        form: "payment-form",
        merchant_id: "8291028192001", // Reemplaza esto por tu public merchant id
        amount: "14.99",
        currency: "USD",
        payment_methods:["credit-card"], // Podrás habilitar más medios de pago.
        inTestEnvironment: true, // Configurado en modo prueba
    });
</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 $49.99</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: '49.99',
  currency: "USD",
  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. Authorization

The back-end is responsible for using the collected token to make an authorization request and then, in case it is approved, to make a capture or cancellation request, depending on the case.

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 authorization endpoint to start the charge.

Python
Javascript
PHP

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"token\":\"QZPnSP1000000b3MG3062555GhIrcYt5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":600,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"fullResponse\":true}"

headers = { 'content-type': "application/json" }

conn.request("POST", "/card/v1/preAuthorization", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

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 this with the received token
    amount: {subtotalIva: 0, subtotalIva0: 600, ice: 0, iva: 0, currency: 'USD'},
    fullResponse: true
  },
  json: true
};

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

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"token":"QZPnSP1000000b3MG3062555GhIrcYt5","amount":{"subtotalIva":0,"subtotalIva0":600,"ice":0,"iva":0,"currency":"USD"},"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’s issuing entity. Once Kushki’s response is obtained, save the ticketNumber since this will be the identifier for later capture and also cancellation.

3.1. Capture (optional)

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

Python
Javascript
PHP

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"ticketNumber\":\"319228478889680318\",\"amount\":{\"currency\":\"PEN\",\"subtotalIva\":0,\"iva\":0,\"subtotalIva0\":600,\"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"))

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: 'PEN', subtotalIva: 0, iva: 0, subtotalIva0: 600, ice: 0},
    fullResponse: true
  },
  json: true
};

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

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"ticketNumber":"319228478889680318","amount":{"currency":"PEN","subtotalIva":0,"iva":0,"subtotalIva0":600,"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();

3.2 Cancel authorization (Optional)

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

Python
Javascript
PHP

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"fullResponse\":true,\"amount\":{\"subtotalIva\":10000,\"subtotalIva0\":0,\"ice\":0,\"iva\":0,\"currency\":\"COP\"}}"

headers = { 'content-type': "application/json" }

conn.request("DELETE", "/v1/charges/1528188291221", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

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: 10000, subtotalIva0: 0, ice: 0, iva: 0, currency: 'COP'}
  },
  json: true
};

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

  console.log(body);
});

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"fullResponse":true,"amount":{"subtotalIva":10000,"subtotalIva0":0,"ice":0,"iva":0,"currency":"COP"}}');

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

4. 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 in authorization: 4349003000047015
Transaction declined in capture: 4547004841271012

5. 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 (they 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.