---
title: "Token: Create"
method: POST
path: "/tokens"
tags: ["Tokens"]
---

# Token: Create

`POST /tokens`

Creates a token with the given `payment_details`.

It is recommended to have a client application make this request directly so that sensitive payment information (e.g. credit card number) doesn't hit your server. Receiving credit card numbers requires your business to be PCI-DSS compliant. Once you turn your customer's details into a token, the token string can safely be sent to your server and used as `payment_details` to a future KOMOJU API request.

A `currency` may be optionally specified. When `currency` is provided, KOMOJU will ensure that the payment made using the new token is in the same currency.

## Request body

- CreateTokenRequest
  - `currency` 'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND' — 3-letter ISO currency code.
  - `payment_details` union, required
    - PaymentDetailsCreditCard
      - `type` 'credit_card', required — Payment method type.
      - `email` string — Customer's email address. Will be used for fraud prevention and payment receipt.
      - `number` string, required — Credit card number.
      - `month` integer, required — Credit card expiration month.
      - `year` integer, required — Credit card expiration year. If this value is less than 100, it will be treated as two digits year in the current century. E.g. If current year is `2024`, `99` means `2099`.
      - `verification_value` string — Credit card verification value (Also known as CVV2 or CVC2).
      - `name` string — Full name of the customer. This attribute takes precedence over `given_name` and `family_name`.
      - `given_name` string — Given name of the customer. **Note:** You should only set this attribute if you have separate fields for given name and family name. Otherwise, you should only set the full name via `name`.
      - `family_name` string — Family name of the customer. **Note:** You should only set this attribute if you have separate fields for given name and family name. Otherwise, you should only set the full name via `name`.
      - `expiry_days` integer — If the payment is not immediately captured, specify how many days before the payment expires. If this value is omitted, the default expiry day shown in the merchant dashboard will be used.
      - `intent` 'one_time' | 'card_on_file' | 'subscription' | 'installment' — Specify the intent of the payment. Specifying this attribute can increase authorization credit card payments authorization rates, especially when using a stored card.
      - `initiator` 'merchant' | 'customer' — Specify the initiator of this payment. Specifying this attribute can increase authorization credit card payments authorization rates, especially when using a stored card. You can set this value to `customer` when the payment is being made for one-time goods or service purchase, or `merchant` for recurring subscription or installment payments.
      - `usage` 'first' | 'used' — Specify whether this payment is the first (`first`) or a subsequent payment in a series (`used`). Specifying this attribute can increase authorization credit card payments authorization rates, especially when using a stored card.
      - `scheme_reference` string — Specify a scheme reference value, which is used to track the chain of multiple related payments. This value can be subscription number for a recurring subscription payments, or installment agreement number for installment payments. Specifying this attribute can increase authorization credit card payments authorization rates, especially when using a stored card.
      - `installments` '3' | '5' | '6' | '10' | '12' | '15' | '18' | '20' | '24' | 'revolving' — Specify the number of installment months or "revolving" payment. This feature only works for some acquirers, and only for `JPY` transactions.
      - `shipping_address_name` string — Shipping address name. This is the recipient's name.
      - `shipping_address_line1` string — Shipping address line 1.
      - `shipping_address_line2` string — Shipping address line 2.
      - `shipping_address_city` string — Shipping address city.
      - `shipping_address_state` string — Shipping address state.
      - `shipping_address_zip` string — Shipping address ZIP code.
      - `shipping_address_country` string — Shipping address country.
      - `billing_address_name` string — Billing address name. This is the paying customer's name.
      - `billing_address_line1` string — Billing address line 1.
      - `billing_address_line2` string — Billing address line 2.
      - `billing_address_city` string — Billing address city.
      - `billing_address_state` string — Billing address state.
      - `billing_address_zip` string — Billing address ZIP code.
      - `billing_address_country` string — Billing address country.
    - PaymentDetailsCreditCardKorea
      - `type` 'credit_card_korea', required — Payment method type.
      - `number` string, required — Credit card number.
      - `month` integer, required — Credit card expiration month.
      - `year` integer, required — Credit card expiration year. If this value is less than 100, it will be treated as two digits year in the current century. E.g. If current year is `2024`, `99` means `2099`.
      - `verification_value` string — Credit card verification value (Also known as CVV2 or CVC2).
      - `corporate_card` boolean — Specify whether this payment card is a corporate card.
      - `social_id` union — This attribute differs whether the payment card is personal or corporate card. - For personal card, you should specify customer's date of birth. - For corporate card, you should specify payment card's corporate number.
        - string — Customer's date of birth in `YYMMDD` format.
        - string — Payment card's corporate number.
      - `first_two_digits_of_pin` string, required — Specify the first four digit of credit card's PIN number.
      - `shipping_address_name` string — Shipping address name. This is the recipient's name.
      - `shipping_address_line1` string — Shipping address line 1.
      - `shipping_address_line2` string — Shipping address line 2.
      - `shipping_address_city` string — Shipping address city.
      - `shipping_address_state` string — Shipping address state.
      - `shipping_address_zip` string — Shipping address ZIP code.
      - `shipping_address_country` string — Shipping address country.
      - `billing_address_name` string — Billing address name. This is the paying customer's name.
      - `billing_address_line1` string — Billing address line 1.
      - `billing_address_line2` string — Billing address line 2.
      - `billing_address_city` string — Billing address city.
      - `billing_address_state` string — Billing address state.
      - `billing_address_zip` string — Billing address ZIP code.
      - `billing_address_country` string — Billing address country.
    - PaymentDetailsCreditCardBrazil
      - `type` 'credit_card_brazil', required — Payment method type.
      - `email` string, required — Customer's email address. Will be used for fraud prevention and payment receipt.
      - `number` string, required — Credit card number.
      - `month` integer, required — Credit card expiration month.
      - `year` integer, required — Credit card expiration year. If this value is less than 100, it will be treated as two digits year in the current century. E.g. If current year is `2024`, `99` means `2099`.
      - `verification_value` string, required — Credit card verification value (Also known as CVV2 or CVC2).
      - `name` string, required — Full name of the customer. This attribute takes precedence over `given_name` and `family_name`.
      - `cpf_or_cnpj` string, required — Specify customer's CPF or CNPJ.
      - `customer_ip` string, required — Specify customer's IPv4 or IPv6-formatted IP address of the customer at the time of payment.
      - `shipping_address_name` string — Shipping address name. This is the recipient's name.
      - `shipping_address_line1` string — Shipping address line 1.
      - `shipping_address_line2` string — Shipping address line 2.
      - `shipping_address_city` string — Shipping address city.
      - `shipping_address_state` string — Shipping address state.
      - `shipping_address_zip` string — Shipping address ZIP code.
      - `shipping_address_country` string — Shipping address country.
      - `billing_address_name` string — Billing address name. This is the paying customer's name.
      - `billing_address_line1` string — Billing address line 1.
      - `billing_address_line2` string — Billing address line 2.
      - `billing_address_city` string — Billing address city.
      - `billing_address_state` string — Billing address state.
      - `billing_address_zip` string — Billing address ZIP code.
      - `billing_address_country` string — Billing address country.
    - PaymentDetailsCreditCardTerminal
      - `type` 'credit_card_terminal', required — Payment method type.
      - `number` string, required — Credit card number.
      - `month` integer — Credit card expiration month.
      - `year` integer — Credit card expiration year. If this value is less than 100, it will be treated as two digits year in the current century. E.g. If current year is `2024`, `99` means `2099`.
      - `sequence_number` string — Specify the sequence number from the credit card terminal
      - `field55` string — Specify the EMV data produced by the terminal.
      - `posDataCode` string — Specify the POS data code produced by the terminal.
      - `track2` string — Specify the data read from track 2 of the payment card.
      - `flowType` string — Specify whether this transaction is a EMV or magnetic stripe transaction. - Use value "1" for EMV transaction. - Use value "2" for magnetic stripe transaction.
      - `shipping_address_name` string — Shipping address name. This is the recipient's name.
      - `shipping_address_line1` string — Shipping address line 1.
      - `shipping_address_line2` string — Shipping address line 2.
      - `shipping_address_city` string — Shipping address city.
      - `shipping_address_state` string — Shipping address state.
      - `shipping_address_zip` string — Shipping address ZIP code.
      - `shipping_address_country` string — Shipping address country.
      - `billing_address_name` string — Billing address name. This is the paying customer's name.
      - `billing_address_line1` string — Billing address line 1.
      - `billing_address_line2` string — Billing address line 2.
      - `billing_address_city` string — Billing address city.
      - `billing_address_state` string — Billing address state.
      - `billing_address_zip` string — Billing address ZIP code.
      - `billing_address_country` string — Billing address country.
  - `platform_details` ProcessingMerchant
    - `processing_merchant_id` string — A unique 25-character alphanumeric resource identifier.

## Response `200`

200 response

- Token
  - `id` string, required — A unique 25-character alphanumeric resource identifier.
  - `resource` 'token', required — Resource type name, always "token".
  - `created_at` string, date-time, required — Timestamp when the token was created.
  - `payment_details` object, required
    - `type` string, required — Payment method type for this token (e.g. "credit_card").
    - `email` string — Email address associated with this token.
    - `phone` string — Phone number associated with this token.
    - `given_name` string — Customer's given name.
    - `family_name` string — Customer's family name.
    - `given_name_kana` string — Customer's given name in katakana.
    - `family_name_kana` string — Customer's family name in katakana.
    - `store` string — Convenience store slug selected for this token (e.g. "seven-eleven").

## Other responses

- `403` — Invalid authorization
- `422` — Failed to create a token for blik
- `502` — Credit card terminal EMV errors

---

[API](https://skmtc.net/komoju/apis/komoju-api.md) · [All operations](https://skmtc.net/komoju/apis/komoju-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/komoju/komoju-api/revisions/65483c40ba32/schema)