Accept a Card Payment

Accept online card payments securely

Web

iOS

Android

This functionality is available for the following models:

☑ Acquirer

☐ Aggregator

To know the card types enabled in each of the affiliation models, please check our supported card brand guide.

This functionality is available for the following models:

☑ Acquirer

☑ Aggregator

To know the card types enabled in each of the affiliation models, please check our supported card brand guide.

You can now immediately create a test account with Kushki from Immediate Affiliation.

¿Are you looking for a plugin?

Check our plugins documentation and install them in just a few clicks on your E-commerce website.

Receiving payments with debit and credit cards in your website means capturing the card details, generating a token, and sending the payment to Kushki for processing.

To keep in mind

Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.

An example of a card payment form would be as shown below:

The payment flow that you will integrate is as shown below:

1. 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 sending that information to the back end to start the payment process.

You have three options to integrate: Kajita, Kushki.js and Kushki.js Hosted Fields.

Kajita

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

Cajita: the first version of the predefined payment form. Not customizable.

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

Kajita will include the validations of the BIN of the card entered by your customer so that the different deferred payment options available are displayed.

Create and customize your Kajita

With Kushki you can create your Kajitas from the Administration Console. Click here to learn how to do this.

Set up Kajita

Include the kushki-checkout.js script in your payment 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 Website

Kajita needs a space within your page. Enter the following code in your website's <body>, where you want the payment form to be displayed.

For Kajita (v.2):

For Cajita (v.1):

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

Then, add the script tag.

For the Kajita (v.2) you can obtain such script from your Administration Console as explained here.

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

This will create a predesigned form on your website to accept payments.

You can use Kajita to offer not only card payments, but also in cash and wire-transfers.

Kushki.js

Use Kushki.js if you need more 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> of your payment page.

Option 2 - npm

Install the package from npm.

Then import it into your code using the following code.

Set up `Kushki` object

Add the following code to your application

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:

Show the deferred options according to the BIN of your customer's card

As soon as your customer's card number is entered, you should check the method of o request deferred options to verify if there are deferred payment options for the BIN of the card entered by the user.

In response to this call, you will receive the type type, the available months and the months of grace, as shown in the following example response. To execute the charge you should use only months.

  {
      type: "all",
      months: ["2", "3", "4", "5", "6", "7"],
      monthsOfGrace: []
    }

To execute the charge you must send the object deferred.

For months with no interest in México, there is a minimum amount depending on the term to defer the transaction.

3 months: $300 MXN

6 months: $600 MXN

9 months: $900 MXN

12 months: $1,200 MXN

18 months: $,1800 MXN

Important

The deferred options that are available to your customer will depend on the credit card BIN's.

According to the response, show the information of deferred options that your customer has available. Make sure to capture their choices, and send them in turn along with the payment details in the deferred object or in the months parameter when you start the payment process with Kushki.

And, for the moment the user submits the form, add the token request and take it to your back-end.

Check the full reference on our Kushki.js reference

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 using 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. Set up your Back-end

The back end is responsible for receiving the token obtained from your front end and starting the payment 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 charges endpoint to initiate the charge.

If you want to make the payment using the deferred option, make sure to send the deferred object with the parameters of grace months and credit type (received when searching the deferred ones for a BIN and selected by the user in the form), together with the charge information, as follows:

JavaScript

Python

PHP

Importante

The deferred object should only be sent in cases where the card has the possibility of making deferred payments, in all other cases, such object should be omitted.

Importante

For payments with American Express cards, the firstName parameter accepts a maximum of 18 characters.

Check our API Reference for more information.

According to the response you obtained, redirect the user to a success or failure page to inform them whether the transaction was approved or declined.

Send notifications to your customers

If you want your customers to be notified of their transactions, make sure to send to our charges endpoint your customer's email address, as part of the object contactDetails. In addition to this, remember to enable the notifications option from your administration console.

3. Test your Integration

You can use some 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

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

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

Kushki's logo must be visible for the customer. You can find our logo in several formats here.

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 must accept only numbers.

The CVV field must be of password type.

The CVV field must allow no more than 4 digits and no less than 3 digits.

The expiration date must be required.

The expiration date must accept only future dates.

The payment button must be disabled after the first click.

If you have enabled the option of email notification to your customers about the transaction result from Kushki, the email parameter of the object contactDetails is required.

Kushki's logo must be visible for the customer. You can find our logo in several formats here.

Accept payments with OTP

Only Web. OTP (One Time Password) is another layer of online protection against fraud.

Accept Webhooks

Manage correctly post-payment events.

Accept a Card Payment

1. Set up your Front-end#

Kajita#

Create and customize your Kajita#

Set up Kajita#

Add Kajita to your Website#

Kushki.js#

Set up Kushki.js#

Option 1 - CDN#

Option 2 - npm#

Set up Kushki object#

Collect User Information and Send it to your Back-end#

Show the deferred options according to the BIN of your customer's card#

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. Set up your Back-end#

3. Test your Integration#

4. Prepare your Certification#

1. Set up your Front-end

Kajita

Create and customize your Kajita

Set up Kajita

Add Kajita to your Website

Kushki.js

Set up Kushki.js

Option 1 - CDN

Option 2 - npm

Set up `Kushki` object

Collect User Information and Send it to your Back-end

Show the deferred options according to the BIN of your customer's card

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. Set up your Back-end

3. Test your Integration

4. Prepare your Certification