3D Secure Without a Session
About using 3DS with the KOMOJU payments API
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/ (Japanese only) for more information.
Many regulations and rules require merchants to support 3D Secure.
KOMOJU supports 3D Secure 2.0 out of the box for our primary integration methods (Hosted Page, Hosted Fields). However for merchants who create payments directly, some extra work is required in order to support 3DS. If you are creating payments directly, please read on.
Creating 3DS Payments Directly: Secure Tokens 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 an authentication_url
in order to activate the token.
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][email protected]" \
-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 Parameter | Type | Description |
---|---|---|
amount | numeric | Payment amount |
currency | string | 3 letter currency code |
return_url | string | URL where customer will be redirected to after payment completion |
payment_details[type] | string | "credit_card" |
payment_details[email] | string | Customer's email address |
payment_details[number] | numeric | Credit card number |
payment_details[month] | numeric | Credit card expiry month |
payment_details[year] | numeric | Credit card expiry year |
payment_details[verification_value] | numeric | "CVV" code on back of card |
payment_details[name] | string | Cardholder name |
Response Parameter | Type | Description |
---|---|---|
id | string | Token ID - you'll want to save this |
verification_status | string | OK , NEEDS_VERIFY , SKIPPED , or ERRORED |
authentication_url | string | URL to send the customer to authenticate with their card issuer |
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
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
POST /api/v1/payments
to process paymentFinally 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 "tax=0" \
-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.
The following fields are required when performing a test transaction.
payment_details[name]
: Test Cardpayment_details[month]
: 08payment_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 |
Updated 6 months ago