Reserve Funds in One-Click Payments

February 09, 2023

Separate the authorization and capture on subscribed cards to create a charge now and capture funds later

Web

iOS

Android

Reserving funds on a card on demand allows you to authorize the availability of funds for a card, but delay the capture of funds for when the service is completed. 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 on the customer’s card for 7 days. If the payment is not captured within that time, it will be automatically canceled and the funds will be released.

How does it work?

To reserve funds from a card on demand, you must:

Create the registration of the card.
Start the authorization with Kushki.
Kushki will attempt 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: If a charge is to be made on the customer’s card.
Cancel authorization: If the authorization is to be canceled and the funds on the card are to be released.

The flow that you will integrate is shown below:

Auth y captura bajo demanda EN

1. Create the card registration

Follow the instructions given in step 1 of the article Generate on-demand payments to learn how to register a card.

If the subscription is successful, you will receive the subscriptionId. The following will be to make an authorization request from your back end and then make a capture or cancellation request, depending on the case.

2. Authorize the charge

With the subscriptionId of your card obtained in the previous step, you will have to call our authorization endpoint to start the reservation of a given amount.

Python
Javascript
PHP

import http.client

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

payload = "{\"amount\":{\"ice\":0,\"iva\":0,\"subtotalIva\":0,\"subtotalIva0\":600,\"currency\":\"PEN\"},\"name\":\"Juan\",\"lastName\":\"Perez\",\"email\":\"juanp@kushkipagos.com\",\"fullResponse\":true}"

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

conn.request("POST", "/subscriptions/v1/card/1574693127852000/authorize", 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/subscriptions/v1/card/1574693127852000/authorize',
  headers: {'content-type': 'application/json'},
  body: {
    amount: {ice: 0, iva: 0, subtotalIva: 0, subtotalIva0: 600, currency: 'PEN'},
    name: 'Juan',
    lastName: 'Perez',
    email: 'juanp@kushkipagos.com',
    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('{"amount":{"ice":0,"iva":0,"subtotalIva":0,"subtotalIva0":600,"currency":"PEN"},"name":"Juan","lastName":"Perez","email":"juanp@kushkipagos.com","fullResponse":true}');

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

$request->setHeaders(array(
  'content-type' => 'application/json'
));

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

echo $response->getBody();

Once the response is obtained, save the ticketNumber, since this will be the identifier for later capture and also cancellation.

3.1. Generate the capture (Optional)

Once funds are required to be collected from the card, a call must be made to our capture endpoint.

Capture the amount you define according to the authorized amount by calling our capture endpoint for on-demand subscriptions, using the card’s subscriptionId and 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", "/subscriptions/v1/card/123442221212/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/subscriptions/v1/card/123442221212/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/subscriptions/v1/card/123442221212/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 the 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, 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).
Kushki’s logo must be visible to the customer. You can find our logo in several formats here.
Make sure to send all the required data as specified in the API Reference.

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 allow no more than 4 digits and no less than 3 digits.
The CVV field must be of password type.
The expiration date must be required.
The expiration date must accept only future dates.
The payment button must be disabled after the first click.
Kushki’s logo must be visible to the customer. You can find our logo in several formats here.
Make sure to send the contact details of your customer-payer (contactDetails), together with the billing details (orderDetails -> billingDetails) and shipping details (if your business model requires it: orderDetails -> shippingDetails), within the request to make the charge. The example of the Body of JSON for the charge can be found at API Reference.