Accepting On-Demand Payments

Guarda los datos de tarjeta de tus clientes para cobrar bajo la lógica que tú definas

Web
iOS
Android

Kushki allows you to securely store a customer’s card details, without necessarily charging an initial fee, and then allow them to make one click payments to speed up the checkout process.

How does it work?

Storing debit and credit card details on your website means capturing the card details, generating a token and sending the information to Kushki for storage, where a subscription identifier will be created for the card. Then, with that identifier, you will be able to make one click charges from your back end as required.

Basically, integrating on-demand payments consists of 2 stages: Registration and charge

The flow that you will integrate is shown below:

Flujo pago con tarjeta on demand EN

1. Registration

The first thing you need to do to generate one click charges is to register your customer’s card. To do so, follow the steps below:

Set up your front end

The front end is responsible for collecting the user’s card details securely, generating a token for such information through Kushki’s servers, and then sending that information to the back end to start the card registration process so that you can charge later.

Use Kushki.js to have more control over the “look & feel” or appearance of your card 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.requestSubscriptionToken({
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);
}
});

Set up your back end

The back end is responsible for receiving the token obtained from your front end and starting the card registration process with Kushki.

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 inscription endpoint to register the card.

  • Javascript
  • Python
  • PHP
const request = require("request");
const options = {
method: 'POST',
url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card',
headers: {'content-type': 'application/json'},
body: {
token: 'gV3ox6100000sAxClU033646vnnJsT83',
planName: 'Gold',
periodicity: 'custom',
contactDetails: {
"documentType": "CC",
"documentNumber": "1009283738",
"email": "test@test.com",
"firstName": "Diego",
"lastName": "Cadena",
"phoneNumber": "+593988734644"
},
amount: {
subtotalIva: 0,
subtotalIva0: 0,
ice: 0,
iva: 0,
currency: 'USD'
},
startDate: '2021-01-01',
},
json: true
};
request(options, (error, response, body) => {
if (error) throw new Error(error);
console.log(body);
});
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
payload = "{\"token\":\"gV3ox6100000sAxClU033646vnnJsT83\",\"planName\":\"Premium\",\"periodicity\":\"custom\",\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"pruebas@kushki.com\",\"firstName\":\"Diego\",\"lastName\":\"Cadena\",\"phoneNumber\":\"+593988734644\"},\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":0,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"startDate\":\"2018-09-25\",\"metadata\":{\"plan\":{\"fitness\":{\"cardio\":\"include\",\"rumba\":\"include\",\"pool\":\"include\"}}}}"
headers = { 'content-type': "application/json" }
conn.request("POST", "/subscriptions/v1/card", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
# Your logic here ...
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"token":"gV3ox6100000sAxClU033646vnnJsT83","planName":"Premium","periodicity":"custom","contactDetails":{"documentType": "CC", "documentNumber": "1009283738", "email": "test@test.com", "firstName": "Diego", "lastName": "Cadena", "phoneNumber": "+593988734644"},"amount":{"subtotalIva":0, "subtotalIva0":0, "ice":0, "iva":0, "currency":"USD"},"startDate":"2018-09-25","metadata":{"plan":{"fitness":{"cardio":"include","rumba":"include","pool":"include"}}}}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
// Your logic here ...

According to the response you obtained, it redirects the user to a success or failure page to inform the customer whether the registration was approved or declined.

Perform an Anti-Fraud Validation (Optional)

For the security of your business, Kushki’s fraud prevention team will ask you, in certain cases or for certain amounts, to activate identity validation when registering cards or receiving payments with them.

How does an Anti-Fraud Validation work?

When trying to register a card or make a payment, Kushki will perform a validation to verify if the document number is associated with the card sent. If the validation is successful, the subscription or payment will be completed correctly; otherwise, we will send you a response so that you can decide how to proceed .

Submit card details

The card information can be submitted for validation either on the subscription creation endpoint or on the one click charge endpoint. Since this service has a cost for each query, performing the validation at the time of creating the inscription is recommended. Make sure that the ignoreWarnings parameter is set in false, and that the type and number of the document, and the customer’s first name, first surname and second surname are included in the contactDetails object, and that the fullResponse parameter is set in true. If you decide to skip this validation, set the ignoreWarnings parameter to true value. __

Receiving the Validation Result

The response to identity validation will be received in the rules object, and there are three possible responses:

ResponseParameters ReceivedWhat to do?
Approved Transaction{"code": "000","message": "TransUnion Approval"}There’s no need to do anything else, the transaction will be sent to create the inscription and, according to the response, you may redirect the user to a success or fail screen to inform the customer whether the card was successfully registered.
Rejected Transacción: (validation was not possible){"code": "006","message": "TransUnion Unavailable"}Check that the parameters documentNumber and documentType have been sent in the object contactDetails and retry.
Declined Transaction{"code": "322","message": "TransUnion Declined"}If the transaction was declined by the validation system, you have two options: 1) Ignoring the alert and creating the subscription: In this case, you must return to the previous step, and make sure that the parameter ignoreWarnings is sent in true, with the same token already generated 2) Accepting the alert and decline the transaction.

2. Charge

Once you have already registered your customer’s card, in order to make a one click charge, it is necessary to perform these simple steps, using the subscriptionId.

Set up your front end

We will take advantage of the fact that our Kushki.js library has been imported and setup previously to use a method that will be very helpful to verify the reliability of the charge.

Generate a charge token and send it to your back end

First, it is necessary to obtain the subscription ID of the card that will be charged.

Then, request the charge token, and send it to your back end.

kushki.requestTokenCharge({
subscriptionId: "1543267242354000" // Replace with your subscription id
}, (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);
}
});

Set up your back end

Once the charge token has been received, simply call our charge endpoint along with the subscriptionId as you deliver your service to your customer under the logic you define.

  • Javascript
  • Python
  • PHP
var request = require("request");
var options = {
method: 'POST',
url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/291929129192912', // Replace this with your subscription ID
headers: {'content-type': 'application/json'},
body: {
language: "es",
token: "1cfaze100000qQ4dtN016410Ow7ot8nd",
planName: 'Gold',
periodicity: 'custom',
amount: {
subtotalIva: 0,
subtotalIva0: 50000,
ice: 0,
iva: 0,
currency: "CLP"
},
deferred: {
months: 6
},
metadata: {
customerId: "123"
},
contactDetails: {
documentType: "CC",
documentNumber: "1009283738",
email: "test@test.com",
firstName: "Diego",
lastName: "Cadena",
phoneNumber: "+593988734644"
},
orderDetails: {
siteDomain: "tuebook.com",
shippingDetails: {
name: "Diego Cadena",
phone: "+593988734644",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Santiago de Chile",
region: "Santiago",
country: "Chile",
zipCode: "170402"
},
billingDetails: {
name: "Diego Cadena",
phone: "+593988734644",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Santiago de Chile",
region: "Santiago",
country: "Chile",
zipCode: "170402"
}
},
productDetails: {
product: [
{
id: "198952AB",
title: "eBook Digital Services",
price: 6990000,
sku: "10101042",
quantity: 1
},
{
id: "198953AB",
title: "eBook Virtual Selling",
price: 9990000,
sku: "004834GQ",
quantity: 1
}
]
},
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/subscriptions/v1/card/291929129192912"
payload = "{\"language\":\"es\",\"token\":\"1cfaze100000qQ4dtN016410Ow7ot8nd\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":50000,\"ice\":0,\"iva\":0,\"currency\":\"CLP\"},\"deferred\":{\"months\":6},\"metadata\":{\"customerId\":\"123\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Cadena\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Santiago de Chile\",\"region\":\"Santiago\",\"country\":\"Chile\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Santiago de Chile\",\"region\":\"Santiago\",\"country\":\"Chile\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":6990000,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9990000,\"sku\":\"004834GQ\",\"quantity\":1}]}}"
headers = { 'content-type': "application/json" }
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
# Your logic here ...
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{\"language\":\"es\",\"token\":\"1cfaze100000qQ4dtN016410Ow7ot8nd\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":50000,\"ice\":0,\"iva\":0,\"currency\":\"CLP\"},\"deferred\":{\"months\":6},\"metadata\":{\"customerId\":\"123\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Cadena\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Santiago de Chile\",\"region\":\"Santiago\",\"country\":\"Chile\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Santiago de Chile\",\"region\":\"Santiago\",\"country\":\"Chile\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":6990000,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9990000,\"sku\":\"004834GQ\",\"quantity\":1}]}}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/291929129192912');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
// Your logic here ...

Cancel a registration (Optional)

If your customer decides to cancel the service or once you stop providing it, in order to cancel the card inscription, simply call our inscription cancellation endpoint from your back end.

  • Javascript
  • Python
  • PHP
const request = require("request");
request({
method: 'DELETE',
url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/213123123123',
headers: {'content-type': 'application/json'}
}, (error, response, body) => {
if (error) throw new Error(error);
console.log(body);
// Insert your logic here...
});
import http.client
conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")
headers = { 'content-type': "application/json" }
conn.request("DELETE", "/subscriptions/v1/card/213123123123", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
# Insert your logic here...
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/213123123123');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
// Insert your logic here...

3. Test your Integration

You may use 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 during charge request (back end): 4349003000047015

If you want to verify the creation of a credit card subscription by performing anti-fraud validation, submit the card numbers below when requesting a subscription token and when making the subscription creation request. The document number and type of document indicated must be included within the contactDetails object:

Approved validation:

  • Credit card: 5642569816497595
  • Document number: 80004393
  • Document type: CC

Rejected validation:

  • Credit card: 5642569816497595
  • Document number: 8000000
  • Document type: CC

Validation not performed:

  • Do not send documentNumber, nor documentType in the contactDetails object.

4. 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 for 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 (they may be less).
  • The CVV field must be required.
  • The CVV field accepts 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 carry out the charge. The example of the Body of JSON for the charge can be found at API Reference

Accept Webhooks

Manage correctly post-payment events.