As you may know, "payment details" refers to the user input required to make a payment. This user input often contains sensitive information subject to regulations such as PCI-DSS - specifically, credit card numbers.

This document is about short-term tokenization of Payment Details. The goal is to "tokenize" credit card inputs on the client browser or app, and then send the token to your server for immediate processing. If you're interested in long-term storage of payment details, see Long-term Tokens.

Tokenizing Credit Card Numbers

When credit card numbers pass through your server, you become subject to PCI-DSS. PCI-DSS can be a serious burden on day-to-day operations. KOMOJU provides a way to avoid from sending raw credit card details to your server, while still letting you use our full suite of payments APIs. We call this "tokenization".

Here we'll walk through steps taken in this recipe:

🏅

Tokenize credit card details

Open Recipe

Step 1: create a Token

Call our Token: Create API with the Payment Details for credit_card.

Authentication	Method	Endpoint
Publishable key	POST	https://komoju.com/api/v1/tokens

Request Attribute	Type	Description
`payment_details[type]`	constant	"credit_card"
`payment_details[name]`	string	Cardholder name.
`payment_details[number]`	string	Credit card number with no spaces, e.g. "4111111111111111".
`payment_details[month]`	string	Two-digit card expiration month.
`payment_details[year]`	string	Two-digit card expiration year.
`payment_details[verification_value]`	string	Short 3~4 digit code on the back of most cards.

The key here is to call this on your front-end application. This ensures that sensitive information flows directly from the customer to KOMOJU. Since we are PCI-DSS compliant, this saves you the burden.

Step 2: save Token ID

In the response, you'll get a Token object.

Response Attribute	Type	Description
`id`	string	Token ID. You can safely pass this value to your back-end and then use it in place of `payment_details` when making payments.

Pass this token to your server.

Step 3: use Token ID

Once you have a Token ID on your server, you can set payment_details to your Token id string for any of the following endpoints:

Payment: Create

Session: Pay

Customer: Create

Caveats: these Tokens can only be used once. Additionally, they will expire after 24 hours of non-use.

Tokenizing non-Credit Card Payment Details

The main purpose of tokenization is to allow for rich payments integrations without PCI-DSS burden. PCI-DSS only affects credit cards, and so using our Tokens API doesn't help much for other payment methods. That said, our Tokens API does still work with any payment method.

For example, you could make the following request

Authentication	Method	Endpoint
Publishable key	POST	https://komoju.com/api/v1/tokens

Request Attribute	Value
`payment_details[type]`	"konbini"
`payment_details[email]`	[email protected]
`payment_details[store]`	seven-eleven

and KOMOJU will give you a valid token ID. When you use this token ID to make a payment, you will get a Payment with status "authorized" and an instructions link for how to pay at Seven Eleven, which you'll need to show to your customer.

The only reasons you might want to do this is:

Your want to re-use code between credit card and other payment method integrations, OR
You are using Hosted Fields Token Mode.