Request a card token

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.

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

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.

3D Secure (3DS) authentication*

Product in beta version in Ecuador 🇪🇨 🔐

We are working on our beta version. Stay tuned for its official release! You can also contact your account manager for more information.

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.tutienda.com/&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.

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 success 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

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

Got a suggestion on this documentation? Contact Us.

curl --location --request POST 'https://api-uat.kushkipagos.com/card/v1/tokens' \ --header 'Public-Merchant-Id;' \ --header 'Content-Type: application/json' \ --data-raw '{ "card": { "name": "John Doe", "number": "5451951574925480", "expiryMonth": "08", "expiryYear": "28", "cvv": "123" }, "totalAmount": 16.98, "currency": "USD" }'

3D Secure (3DS) authentication*#

callbackUrl#

Example of a successful authentication callback#

Example of a callback with authentication problem#

Request

Responses

3D Secure (3DS) authentication*

callbackUrl

Example of a successful authentication callback

Example of a callback with authentication problem