Receive payments with authorization and capture

With the authorization and capture service, you can create a charge now and capture the funds in the future. Review this article to know how this process works.

Web

iOS

Android

This functionality is available for the following models:

☑ Acquirer

☑ Aggregator

Receiving one-time card payments under the authorization and capture scheme guarantees the availability of the amount on the customer’s card for a maximum of 7 days for debit and 28 days for credit cards. If the payment is not captured within that time, the funds retained will be released by the issuing bank back to the cardholder.

Important

Please note that, due to our risk policies, the available payment methods and the type of integration may vary at the time you formalize the affiliation. We will guide you on how to proceed and apply to your business.

An example of what you will integrate is as follows:

Flow

The flow you will integrate will be as follows:

1. Obtain the single-use payment token

The responsibility of the front end is to securely collect the user’s card information, tokenize that information through Kushki’s servers, and then send that information to the back-end to initiate the authorization process.

You have three options for integrations: kajita, Kushki.js and Kushki.js Hosted Fields.

Kajita

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

Cajita: the first version of the payment form. It is not customizable.

Kajita: the second version. It allows you to customize your payment forms from your Admin Console and even have multiple Kajita versions, for example, one for each payment method.

Create and customize your Kajitas

With Kushki, you can create your Kajitas from the Admin Console. Click here to learn how to do it.

Set up Kajita

Include the kushki-checkout.js on your 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.

Add Kajita to your site

Kajita needs space within your page.
Enter the following code in the <body> of your site where you want the payment form to be displayed.

For Kajita (v.2)

For Kajita (v.1)

Remember to configure the form action according to the corresponding endpoint in your back-end to obtain the token.

Next, add the script tag.

For the Kajita (v.2) you can obtain this script from your Admin Console as explained in the Payment Kajitas article.

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

This will create a predefined form on your page to accept payments.

You can use Kajita to offer not only card payments but also cash and bank transfers bancarias.

Kushki.js

Use kushki.js if you need greater 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> on your payment page.

Option 2 - NPM

Install the package from npm.

Then import it into your code.

Configure the `Kushki` object

Add the following code to your application

Collect user information and send it to your back-end

First, add the form to your payment page with the required fields. You can design it any way you like.

For example:

Then, when the user submits the form, request the token and send it to your back-end.

Check out the full reference in our Kushki.js references

Kushki.js Hosted Fields

With Hosted Fields, included in Kushki.js, you can securely collect customer payment information through fields stored on Kushki infrastructure. Returns a token which allows the payment flow to continue from the back-end.

Import Kushki.js Hosted Fields into your app

Option 1 - CDN

Import the Kushki.js Hosted Fields library into your application via a <script> tag inside the <body> tag. Once imported, you will be able to access the resources described below to create a payment flow with Kushki.

It is necessary to import the libraries kushki.min.js (which brings the necessary code to store your merchant's credentials) and card.min.js (the module that brings the necessary functionalities for the flow with card payments).

Option 2 - NPM

Install the Kushki.js Hosted Fields library as an npm package inside your application with the following code:

Option 3 - YARN

Install the Kushki.js Hosted Fields library as a yarn package inside your application with the following code:

Create an instance of `KushkiOptions`

To use the Kushki.js Hosted Fields library, it is necessary to create an instance of KushkiOptions which allows you to set the public key of the work environment (test or production) through the init() method.

Note: When you are ready to accept real payments, you need to replace the test key with the production key.

Add the following code to your application:

Check the reference for more information about the KushkiOptions instance.

Initialize the form on the front-end

Follow the steps below to render the hosted fields. This way, your clients will be able to enter the necessary data to carry out transactions.

Step 1. Define containers for hosted fields.

Before calling the initCardToken() method, it is required to place the necessary elements to be able to render each hosted field.

Step 2. Create an instance of `CardOptions`

Create an instance of CardOptions with the transaction information, such as the amount, currency, among other parameters.

Step 3. Render hosted fields with the initCardToken() method

After creating an instance of CardOptions, you need to call the initCardToken() function to initialize an instance of ICard.

Check the reference for more information on form initialization.

Request a token to continue the payment flow

Request a card payment token that you can later use to charge a customer with the endpoint to make a one-time payment or to create a recurring charge.

To obtain a card payment token, it is necessary to call the requestToken() method on the previously initialized card instance. This method performs 3DS, OTP and Sift Science validations automatically. Also, validate that all the fields are correct; otherwise it will throw an exception.

Note: If the deferred option is available for your merchant, the deferred object will be returned along with the token. In order to select the non-interest-bearing months to defer the purchase, a div tag must be placed with the id of deferred_id (<div id="deferred_id"></div>) and define within the CardOptions instance in the fields object the id deferred_id. The fields available within deferred vary depending on the country. Consult the reference for more information on deferred.

Once the token is obtained, send it to your back-end to continue the payment flow.

To perform validations using OTP, check out OTP validation.

See the reference for more information about the token request.

2. Perform the authorization

The responsibility of the back-end is to use the collected token to make an authorization request. If approved, perform a capture or void, depending on the case

When the user submits the form, your front-end transfers a token to an endpoint you have specified. With this token, you should make a call to our authorization endpoint to initiate the authorization of funds.

JavaScript

Python

PHP

You can learn more in our API references.

3. Kushki verifies authorization

Kushki will validate the availability of funds with the card-issuing entity.
Once you receive a response from Kushki, save the ticketNumber, as this will be the identifier for the reauthorization, capture or cancellation.

4. Reauthorize the charge (optional)

Extend the validity or amount of the authorization before capturing your funds by calling our reauthorization endpoint.

JavaScript

Python

PHP

Keep in mind

If you only want to extend the validity of the authorization, the value of the amount must be sent in 0.

5. Capture or release the funds

5.1 Perform the capture (optional)

Important

The maximum amount to be captured may be 10% higher than the total amount of the initial authorization plus the n reauthorizations that may be executed.

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

JavaScript

Python

PHP

You can learn more in our API reference.

5.2 Authorization void (optional)

If you need to void an authorization to release the funds to the cardholder, you can do so by calling charge void endpoint, using the ticketNumber obtained in the authorization.

JavaScript

Python

PHP

You can learn more in our API reference.

Test your integration

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

Approve transaction: 5451951574925480.

Transaction declined at token request(front-end): 4574441215190335.

Trabsaction declined at authorization: 4349003000047015.

Transaction declined at captur: 4547004841271012.

Prepare your certification

Consider 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).

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 information (contactDetails), along with billing information ( "orderDetails"."billingDetails") and shipping informations (if your business model requires it: "orderDetails"."shippingDetails"), within the request to make the change.

The Kushki logo must be visible to the customer. You can find our logo in various formats here.

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

The cardholder name is required.

The card number field is required.

The card number field accepts only numbers.

The card number field has a maximum of 16 digits (it can be less).

The CVV field is required.

The CVV field accepts only numbers.

The CVV fields must be of password type.

The CVV field allows a maximum of 4 digits and a minimum of 3

The expiration date is required.

The expiration date must accept only future dates.

The payment button is disabled after the first click.

If your have enabled the option of email notification to your customers about the outcome of transactions from Kushky, the emailparameter of the object contactDetails is required.

The Kushki logo must be visible to the customer. You can find our logo in various formats here.

Receive payments with authorization and capture

Flow#

1. Obtain the single-use payment token#

Kajita#

Create and customize your Kajitas#

Set up Kajita#

Add Kajita to your site#

Kushki.js#

Set up Kushki.js#

option 1 -CDN#

Option 2 - NPM#

Configure the Kushki object#

Collect user information and send it to your back-end#

Kushki.js Hosted Fields#

Import Kushki.js Hosted Fields into your app#

Option 1 - CDN#

Option 2 - NPM#

Option 3 - YARN#

Create an instance of KushkiOptions#

Initialize the form on the front-end#

Step 1. Define containers for hosted fields.#

Step 2. Create an instance of CardOptions#

Step 3. Render hosted fields with the initCardToken() method#

Request a token to continue the payment flow#

2. Perform the authorization#

3. Kushki verifies authorization#

4. Reauthorize the charge (optional)#

5. Capture or release the funds#

5.1 Perform the capture (optional)#

5.2 Authorization void (optional)#

Test your integration#

Prepare your certification#

Flow

1. Obtain the single-use payment token

Kajita

Create and customize your Kajitas

Set up Kajita

Add Kajita to your site

Kushki.js

Set up Kushki.js

option 1 -CDN

Option 2 - NPM

Configure the `Kushki` object

Collect user information and send it to your back-end

Kushki.js Hosted Fields

Import Kushki.js Hosted Fields into your app

Option 1 - CDN

Option 2 - NPM

Option 3 - YARN

Create an instance of `KushkiOptions`

Initialize the form on the front-end

Step 1. Define containers for hosted fields.

Step 2. Create an instance of `CardOptions`

Step 3. Render hosted fields with the initCardToken() method

Request a token to continue the payment flow

2. Perform the authorization

3. Kushki verifies authorization

4. Reauthorize the charge (optional)

5. Capture or release the funds

5.1 Perform the capture (optional)

5.2 Authorization void (optional)

Test your integration

Prepare your certification