Secure Token API

You can implement 3D Secure 2.0 supported credit card payments by using Secure Token API.

What is 3D Secure 2.0?

3D Secure 2.0 is a protocol designed to help prevent credit card fraud by providing an additional means of customer authentication. Please see https://ja.komoju.com/blog/news/3d-secure/ for more information (the page is in Japanese).

In accordance with card scheme regulations, merchants need to perform measures preventing fraudulent credit card transactions such as 3D Secure 2.0. So please implement Secure Token API in order to follow the regulations.

KOMOJU is gradually preparing 3-D Secure 2.0 support for all credit card transactions. Please note that Secure Token API may not be available depending on your merchant yet.

The flow of Secure Token API

The flow of Secure Token API is similar to our existing Tokens API. The difference is that your system needs to navigate customers to authentication_url on the API response in order to activate the generated Secure Token.

ShopShopKOMOJUKOMOJUCustomerCustomerPOST /api/v1/secure_tokens/Check `verification_status=NEEDS_VERIFY`Redirect to `authentication_url`Perform 3D Secure 2.0Redirect to `return_url`GET /api/v1/secure_tokens/{id}Check `verification_status=OK`POST /api/v1/paymentsCheck `payment.status=captured`Webhook `payment.captured`Deliver goods or service

1. Generate Secure Token

First, call POST /api/v1/secure_tokens API with credit card payment details. The response includes Secure Token information.


curl -X POST https://komoju.com/api/v1/secure_tokens \
    -u sk_12345: \
    -d "amount=1000" \
    -d "currency=JPY" \
    -d "return_url=https://example.com/complete" \
    -d "payment_details[type]=credit_card" \
    -d "payment_details[email]=test@example.com" \
    -d "payment_details[number]=4100000000000100" \
    -d "payment_details[month]=08" \
    -d "payment_details[year]=2025" \
    -d "payment_details[verification_value]=123" \
    -d "payment_details[name]=Test Card"

{
  "secure_token": "tok_1234567890abcdefghijklmnop",
  "verification_status": "NEEDS_VERIFY",
  "authentication_url": "https://komoju.com/three_d_secure_service/offsite?token=tok_1234567890abcdefghijklmnop"
}
Request Parameters Type Description
amount numeric Payment amount
currency string 3 letter ISO currency code used to pay
return_url string URL where customers are redirected after a payment has been completed
payment_details[type] string Value of credit_card
payment_details[email] string The e-mail address used to send the payment receipt to
payment_details[number] numeric Credit card number
payment_details[month] numeric Expiry month
payment_details[year] numeric Expiry year
payment_details[verification_value] numeric CCV security number
payment_details[name] string Customer name
Response Parameters Type Description
secure_token string Token
verification_status string OK, NEEDS_VERIFY, SKIPPED or ERRORED
authentication_url string The URL for customers to perform 3D Secure 2.0 authentication

Please skip Step 2 and 3 when the verification_status is OK or SKIPPED.

When the verification_status is ERRORED, 3D Secure 2.0 authentication failed to initialize and the Secure Token is unable to be used. Please check the payment_details and retry the request.

2. Redirect to authentication_url

Please redirect customers to authentication_url when the verification_status is NEEDS_VERIFY so that customers can perform 3D Secure 2.0 authentication.

3. Request the authentication result

Customers are redirected to return_url sent with POST /api/v1/secure_tokens. KOMOJU adds secure_token_id=[secure token id] to its HTTP parameters.

After your system received the redirection to redirect_url, you can call GET api/v1/secure_tokens/:id to get the authentication result.

When the verification_status is ERRORED, 3D Secure 2.0 authentication failed to initialize and the Secure Token is unable to be used. Please check the payment_details and retry the request or ask customers to use another credit card.


curl -X GET https://komoju.com/api/v1/secure_tokens/tok_1234567890abcdefghijklmnop \
    -u sk_12345:

{
  "secure_token": "tok_1234567890abcdefghijklmnop",
  "verification_status": "OK",
}

4.Call POST /api/v1/payments to process payment

Finally you can request POST /api/v1/payments by using Secure Token when verification_status is OK or SKIPPED.

Note, SKIPPED status means authentication was skipped because of a system error such as connection error with the 3D Secure 2.0 authentication server. In this case, you may continue processing the payment or retry authentication.

The sum of amount and tax should be equal to the amount value given from the initial Secure Token API request. Omitting tax means tax=auto so tax will be calculated automatically. So we recommend using tax=0.

curl -X POST https://komoju.com/api/v1/payments \
-u sk_12345: \
-d "amount=1000" \
-d "currency=JPY" \
-d "payment_details=tok_1234567890abcdefghijklmnop"

Test Cards

Please use the test cards below in order to test Secure Token in test mode.

These credit card numbers are only available in test mode. If you would like to run a live transaction, you will need to use a real credit card.

The following fields are required when performing a test transaction.

  • payment_details[name] : Test Card
  • payment_details[month] : 08
  • payment_details[year] : 2025

Authentication success

These card numbers can be used to complete a transaction without an authentication challenge.

Card Number Type
4100000000000100 Visa
5100000000000107 Mastercard
3528000000000106 JCB

Authentication success with second authentication

These card numbers can be used to test transactions with a password challenge via authentication_url. Please use 123456 to pass the second authentication.

Card Number Type
4100000000005000 Visa
5100000000005007 Mastercard
3528000000005006 JCB

Authentication rejected

These card numbers can be used to test a rejected authentication after accessing authentication_url and being redirected to return_url.

Card Number Type
4100000000500000 Visa
5100000000500007 Mastercard
3528000000500006 JCB

Authentication failed on second authentication

These card numbers can be used to test transactions with a challenge password. Please use 111111 to simulate a failed authentication.

Card Number Type
4100000000300005 Visa
5100000000300002 Mastercard
3528000000300001 JCB