Reserve On-Demand Funds

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

Web
Android
iOS

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:

  1. Create the registration of the card.
  2. Start the authorization with Kushki.
  3. Kushki will attempt authorization with the card’s issuing entity.
  4. 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