--- title: "SecureToken: Create" method: POST path: "/secure_tokens" tags: ["SecureTokens"] --- # SecureToken: Create `POST /secure_tokens` Creates a SecureToken with the given credit card `payment_details` or `customer` ID. There are two ways to create a SecureToken: - Using `payment_details` with credit card information. - Using `customer` ID, which is a unique identifier for a customer created via the [Customer: Create](https://doc.komoju.com/reference/createcustomer) endpoint. Customer's saved payment details will be used as `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 create a secure token using a customer's credit card details, you can redirect the customer to the authentication url to perform 3DS authentication. Once a secure token has been authenticated, the secure token id can safely be sent to your server and used as `payment_details` to a future KOMOJU API request. ## Request body - union - CreateSecureTokenRequestWithPaymentDetails - `amount` integer, required — Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - `currency` 'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND', required — 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. - `return_url` string, required - `platform_details` ProcessingMerchant - `processing_merchant_id` string — A unique 25-character alphanumeric resource identifier. - CreateSecureTokenRequestWithCustomer - `amount` integer, required — Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - `currency` 'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND', required — 3-letter ISO currency code. - `customer` string, required — To use instead of `payment_details`, specify customer's identifier for this SecureToken. This identifier can be obtained from [Customer: Create](https://doc.komoju.com/reference/createcustomer) endpoint. - `return_url` string, required - `platform_details` ProcessingMerchant - `processing_merchant_id` string — A unique 25-character alphanumeric resource identifier. ## Response `200` 200 response - SecureToken - `id` string, required — A unique 25-character alphanumeric resource identifier. - `created_at` string, date-time, required — Timestamp when the SecureToken was created. - `verification_status` 'OK' | 'NEEDS_VERIFY' | 'ERRORED' | 'SKIPPED' | 'CREATED' | 'EXPIRED', required — Current 3DS verification status of this SecureToken. - `authentication_url` string — URL to redirect the customer to for 3DS authentication. Only present when verification_status is "NEEDS_VERIFY". - `three_d_secure_account` object — 3DS Server account details. Only present when set on the SecureToken. - `acquirer_mid` string, nullable, required — Acquirer Merchant ID, or null if not configured. - `acquirer_bin` string, nullable, required — Acquirer BIN, or null if not configured. - `three_ds_auth_result` ThreeDsAuthResult - `dsReferenceNumber` string — Directory Server reference number for this 3DS transaction. - `acsReferenceNumber` string — Access Control Server reference number assigned by the card scheme. - `threeDSRequestorTransID` string — 3DS requestor transaction ID generated by the merchant's 3DS SDK. - `acsTransID` string — Access Control Server transaction ID assigned by the card issuer. - `dsTransID` string — Directory Server transaction ID for this authentication. - `eci` string — Electronic Commerce Indicator indicating the authentication outcome. - `messageVersion` string — Version of the 3DS protocol used (e.g. "2.1.0"). - `authenticationType` string — Authentication type used for this 3DS transaction. - `authenticationValue` string — Cardholder Authentication Verification Value (CAVV) from the issuer. - `transStatus` string — Transaction status code (e.g. "Y" for authenticated, "N" for not authenticated). - `threeDSServerTransID` string — 3DS Server transaction ID assigned by the 3DS server. ## Other responses - `403` — Invalid authorization - `422` — Failed to create a SecureToken --- [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)