Receive OneClick payments with authorization and capture

July 31, 2024

Learn about the integration steps of the authorization and capture service through which you can obtain the payment token, perform the authorization, and execute the fund capturing.

Web

iOS

Android

This functionality is available for the following models:

☑ Acquirer
☐ Aggregator

Receive OneClick payments using the authorization and capture scheme enable secure storage of your customer’s card data, guaranteeing fund availability on the customer’s card for a maximum of 7 days for debit cards and 28 days for credit cards. If the payment is not captured at that time, the held funds will be released by the issuing bank back to the cardholder.

Flow

The flow you will integrate will be as follows:

One-click payment flow with authorization and capture for Colombia

1. Create card enrollment

The first step in generating OneClick payments with the authorization and capture scheme is to enroll your customer’s card. To perform the enrollment, follow the instructions given in the relevant article Generate one click payments.

If the subscription is successful, you will receive thesubscriptionId. The next step will be to make an authorization request from your back-end and then proceed with capture or unsubscription requests as needed, depending on the case.

2. Authorize the charge

With the subscriptionId of your card received in the previous step, you will need to make a call to our authorization endpoint to initiate the reservation of a given amount.

Javascript
Python
PHP

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: 50000, currency: 'COP'},
    name: 'John',
    lastName: 'Doe',
    email: 'user@test.com',
    orderDetails: {siteDomain: 'tuebook.com', 
        shippingDetails: {name: 'John Doe', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Bogotá', region: 'BogotáDC', country: 'Colombia', zipCode: 170402},
    billingDetails: {name: 'John Doe', phone: +593988734644, address: 'Calle 13 Avenida 39 40', city: 'Bogotá', region: 'BogotáDC', country: 'Colombia', zipCode: 170402}
  },
  fullResponse: v2
  },
  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 = "{\"amount\":{\"ice\":0,\"iva\":0,\"subtotalIva\":0,\"subtotalIva0\":50000,\"currency\":\"COP\"},\"name\":\"John\",\"lastName\":\"Doe\",\"email\":\"userD@test.com\",\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\": \"John Doe\",\"phone\":\"+593988734644\",\"address\":\"13th Street 39th Avenue 40\",\"city\":\"Bogotá\",\"region\":\"BogotáDC \",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"John Doe\",\"phone\":\"+593988734644\",\"address\":\"13th Street 39th Avenue 40\",\"city\": "Bogotá","region": "BogotaDC","country": "Colombia","zipCode": \"170402\"}},\"fullResponse\":v2}

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"))

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

$body = new http\Message\Body;
$body->append('{"amount":{"ice":0,"iva":0,"subtotalIva":0,"subtotalIva0":50000,"currency":"COP"},"name":"John","lastName":"Doe","email":"user@test.com","orderDetails": {"siteDomain":"tuebook.com","shippingDetails":{"name":"John Doe","phone":"+593988734644","address":"13th Street 39th Avenue 40","city": "Bogotá","region":"BogotáDC","country":"Colombia","zipCode":"170402"},"billingDetails":{"name": "John Doe","phone":"+593988734644","address":"13th Street 39th Avenue 40","city": "Bogotá","region":"BogotáDC","country":"Colombia","zipCode": "170402"}},"fullResponse":v2}');

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

3. Kushki verifies authorization

Kushki will validate the availability of funds with the card issuer. Once you have received Kushki’s response, save theticketNumber as this will be the identifier for later capture as well as cancellation.

4. Capture or release funds

4.1. Performs capture (Optional)

Once you are required to collect the funds from the card, capture the amount you define according to the authorized by calling our capture endpoint for subscriptions OneClick, using the subscriptionId of the card and ticketNumber obtained in the authorization.

Javascript
Python
PHP

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: 'COP', subtotalIva: 0, iva: 0, subtotalIva0: 50000, ice: 0},
    fullResponse: v2
  },
  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\":\"COP\",\"subtotalIva\":0,\"iva\":0,\"subtotalIva0\":50000,\"ice\":0},\"fullResponse\":v2}"

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"))

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

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

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

4.2. Void authorization (optional)

If you need to void an authorization for funds to be released to the cardholder, you can do so by calling our void of collections 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: v2,
    amount: {subtotalIva: 0, subtotalIva0: 50000, ice: 0, iva: 0, currency: 'COP'}
  },
  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\":v2,\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":50000,\"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"))

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

$body = new http\Message\Body;
$body->append('{"fullResponse":true,"amount":{"subtotalIva":0,"subtotalIva0":50000,"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();

Test your integration

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

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

Prepare Your Certification

Take into consideration the following guidelines to pass the technical certification (required to obtain production credentials):

Tax calculations are correct.
Do not store sensitive card data in your database (full card number, CVV, etc.).
On-screen messages according to Kushki responses.
Save and record all Kushki responses (required in case support is needed).
The Kushki logo must be visible to the customer. You can find our logo in various formats here.
Make sure you submit all the required data specified in the API reference.

If you are using Kushki.js, also consider the following:

The cardholder’s name is required.
The card number field is required.
The card number field accepts only numbers.
The card number field accepts a maximum of 16 digits (may be fewer).
The CVV field is required
The CVV field accepts only numbers.
The CVV field allows a maximum of 4 digits and a minimum of 3.
The CVV field must be of password type.
The expiration date is required.
The expiration date must accept only future dates.
The payment button is disabled after the first click.
The Kushki logo must be visible to the customer. You can find our logo in various formats here. -Make sure to send your customer-payer’s contact information (contactDetails), along with the billing ( orderDetails -> billingDetails)and shipping information (if your business model requires it: orderDetails -> shippingDetails),within the request to make the charge. You can find an example of the JSON Body for the charge in API reference.