Request a card token

Request a card token that can later be used to charge a customer using the charge
endpoint.

Important to consider: If you are using this option to request the token, be sure to comply with all the PCI requirements to handle card data on your servers.

Token expiration
Tokens will expire in 30 minutes and can be used only for a single transaction (even if the transaction was wrong). You will need to request a new token when it expires.

Note: The token delivered by Kushki only encrypts and sends information. If you want to store the card information for future purchases, go to the One-Click & Scheduled Payments section.

Recurring transactions*

Send the transactionMode parameter for request a recurring charge token that can later be used to create a recurring charge as follows:

initialRecurrence: Merchants must generate a token by sending complete card information (number, expiration date, cvv, etc) to register it. A token will be returned to continue the payment.

subsequentRecurrence: The merchant will be able to generate a token by sending the data of the previously sent card with an initialRecurrence, with this the merchant will be able to omit the entry of the CVV and make a charge later with the current flow.

NOTE: If you want to process a recurring charge with an external engine, you must skip sending the CVV.

3D Secure (3DS) authentication*

To authenticate a card through 3D Secure, in addition to the information required to generate a token, the fields listed below must be submitted

PROPERTY	POSSIBLE VALUES	DESCRIPTION
authValidation	`url` `iframe`	Define the desired integration type for 3DS authentication. Use `url` for redirection or `iframe` for embedding.
callbackUrl	string	Callback where the 3D Secure authentication response will be sent.

If the transaction triggers a 3D Secure authentication rule on the merchant, in addition to the token, the fields listed below will be returned

PROPERTY	POSSIBLE VALUES	DESCRIPTION
url	string	URL to be used for 3D Secure authentication.
secureService	`3dsecure`	Indicates the transaction authentication service.
secureId	string	Security ID for the transaction.

Example

{
    "token": "sBkQ7F110000tI1HVq116862fd5Ah3mG",
    "url": "https://uat-auth.kushkipagos.com?token=sBkQ7F110000tI1HVq116862fd5Ah3mG&merchantId=306cb10581bb4acb9a2bfc77e163c482&bin=NDM0OTAwMzA=&callbackUrl=https://www.kushkipagos.com/callback/&isSandbox=false",
    "secureService": "3dsecure",
    "secureId": "1f5584db-0c5b-c729-a19c-6eb0283ca448"
}

In the url field will be the url that will need to be displayed to the cardholder for 3D Secure authentication, if necessary. For more detailed information, visit the 3D Secure API authentication guide.

For more information about 3D Secure, see Accept payments with 3DS.

NOTE: To enable 3DS in test mode in your merchant, it is required to have an additional configuration performed by Kushki.

callbackUrl

The callback function will let you know if the 3D Secure authentication was successful or if there were any problems during the process. This url will be called automatically after authenticating, through a 301 redirect by making a GET request to the url sent in the callbackUrl field, sending the parameters of the response in the url (path parameters).

Note: The boolean parameter sucess will indicate whether the transaction was successfully authenticated (true) or if there was a problem with 3D Secure authentication (false). If it is true, you can proceed to make the charge. If false, the cardholder will have up to 3 attempts to retry authentication before the transaction is declined.

PROPERTY	TYPE	DESCRIPTION
success	boolean	Indicates whether 3D Secure authentication was successful or not.
token	string	Token returned by Kushki to be used when making a charge in case 3D Secure authentication has been successful.
message	string	In case there is a problem during authentication, the reason for the problem will be returned here.

Example of a successful authentication callback

https://www.tutienda.com/?success=true&token=cfa0bfec88324bd7a5c6c1ad9135a846

Example of a callback with authentication problem

https://www.tutienda.com/?success=false&message=Error%20en%20la%20validación%20de%203DS&token=cfa0bfec88324bd7a5c6c1ad9135a846

Token expiration#

Recurring transactions*#

3D Secure (3DS) authentication*#

callbackUrl#

Example of a successful authentication callback#

Example of a callback with authentication problem#

Request

Responses

Token expiration

Recurring transactions*

3D Secure (3DS) authentication*

callbackUrl

Example of a successful authentication callback

Example of a callback with authentication problem