Tokenizing Payment Details
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:
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:
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.
Updated 5 months ago