---
title: "3Dセキュア 2.0"
description: "Secure Token APIは、KOMOJU上のクレジット決済において、3D Secure 2.0をサポートするためのAPIです。"
url: "https://docs.komoju.com/ja/docs/development/testing-3ds"
source_url: "https://docs.komoju.com/ja/docs/development/testing-3ds.md"
language: ja
last_modified: "2026-03-31"
---

3D Secure 2.0とは、クレジットカード決済の詐欺利用を防止するための本人認証プロトコルです。詳しくは[こちら](https://ja.komoju.com/blog/news/3d-secure/)をご覧ください。

2018年6月1日に施行された「改正割賦販売法」において義務付けられている不正使用対策の要件を満たすものですので、APIによる決済を導入の方は、ぜひSecure Token APIへの対応をお願いいたします。

（API以外による導入の場合、自動的にKOMOJU上で処理するので対応の必要はありません。）

[ホストページ](https://docs.komoju.com/ja/docs/integration-guides/web-integrations/introduction-to-hosted-page.md)、[ホストフィールド](https://docs.komoju.com/ja/docs/integration-guides/introduction-to-hosted-fields.md)をご利用の方、3D Secure 2.0は既にサポートされています。本ドキュメントはダイレクトにペイメントAPIを使用するマーチャント対象です。

# Secure Token APIの流れ

Secure Token APIの基本的な流れは、既存の[Tokens API](/docs/tokens<!-- TODO: update link -->)と似ています。Secure Token APIでは、`authentication_url`に記載されたURLへアクセスして認証を行い、生成されたSecure Tokenを有効化する必要があります。

![](https://files.readme.io/aa86e486053e921ac8e77238e8c8240a4fb7a39f1e67bf2ef930df79cd2bd5dc-e06ea4e-crap.svg)

## 1. Secure Tokenの作成

まずはじめに、`POST /api/v1/secure_tokens`にクレジットカード決済の情報をリクエストします。リクエストに成功すると、KOMOJUはSecure Tokenを作成し、その情報をレスポンスとして返します。

```shell
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"

```

```json
{
  "secure_token": "tok_1234567890abcdefghijklmnop",
  "verification_status": "NEEDS_VERIFY",
  "authentication_url": "https://komoju.com/three_d_secure_service/offsite?token=tok_1234567890abcdefghijklmnop"
}

```

| リクエストパラメータ | タイプ | 詳細 |
| --- | --- | --- |
| `amount` | numeric | 金額 |
| `currency` | string | アルファベット3文字の通貨コード |
| `return_url` | string | ユーザーが認証を完了した後にリダイレクトされるURL |
| `payment_details[type]` | string | "credit_card" |
| `payment_details[email]` | string | ペイメント受領時に送信するメールアドレス。 |
| `payment_details[number]` | numeric | クレジットカード番号 |
| `payment_details[month]` | numeric | 有効期限月 |
| `payment_details[year]` | numeric | 有効期限年 |
| `payment_details[verification_value]` | numeric | "CVV" セキュリティ番号 |
| `payment_details[name]` | string | クレジットカードの所有者名（アルファベット） |

| レスポンスパラメータ | タイプ | 詳細 |
| --- | --- | --- |
| `secure_token` | string | 生成されたSecure TokenのID |
| `verification_status` | string | `OK`, `NEEDS_VERIFY`, `SKIPPED`, `ERRORED`のいずれかの値 |
| `authentication_url` | string | 3D Secure 2.0の認証を行うURL |

`verification_status` の値が OK あるいは `SKIPPED` の場合、手順2および手順3はスキップできます。

なお、 `verification_status` が `ERRORED` の場合、Secure Tokenの生成が失敗しています。リクエスト内容を確認いただくか、再度、Secure Token の生成からやりなおしてください。

## 2. 認証画面へリダイレクトする

レスポンスに含まれる `verification_status` の値が `NEEDS_VERIFY` の場合、お客様を`authentication_url` へリダイレクトしてください。そこでお客様の3D Secure 2.0の認証が行われます。

## 3. 認証終了後、認証結果をリクエストする

客様の3D Secure 2.0の認証が終了しますと、お客様はSecure Token作成時にリクエストした return_url へリダイレクトされます。この際、HTTPパラメータに`secure_token_id=[secure token id]`が付与されております。

`return_url` へのリダイレクトが確認できましたら、`GET api/v1/secure_tokens/:id` にリクエストを送信して、認証結果を確認してください。

もしレスポンスに含まれる `verification_status` が `ERRORED` だった場合、お客様は3D Secure 2.0の認証が失敗したこととなり、決済へ進むことはできません。再度、Secure Tokenの作成からやり直していただくか、別のカードを使う等をお客様にお知らせしてください。

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

```

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

```

## 4. Secure Tokenを用いて決済APIをリクエストする

`verification_status` が OK もしくは `SKIPPED` となっていれば、そのSecure Tokenは決済APIで利用することができます。

`SKIPPED` は、3D Secure 2.0認証サーバとの通信障害など、なんらかの理由で認証が実行できない時に返ってきます。`SKIPPED` の状態では3D Secure 2.0 認証は行われていないことを意味するため、必要に応じて再試行するか決済を続けるかお選びください。

決済APIで指定する `amount` および tax の合計値は、Secure Token APIで指定した `amount` の値と同じである必要があります。tax を未指定にすると auto として扱われて自動で計上されるため、 `tax=0` を指定することを推奨します。

```shell
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モードで挙動を確認したい場合、下記のテスト用カード番号およびテスト用顧客情報を利用してください。名義およびCVVは任意の値を、有効期限は将来の日付を指定してください。

3DS環境の信頼性とパフォーマンス向上のため、KOMOJUでは基礎となる3Dセキュア（3DS）インフラストラクチャベンダーのアップグレードを実施しています。**2026年9月1日以降は、新しいテストカードをご使用ください。**

## 認証成功 (3DS フリクションレス)

認証チャレンジなしで取引を完了できます。

| カード番号 | タイプ |
| --- | --- |
| 4100000000000100 | Visa |
| 5100000000000107 | Mastercard |
| 3528000000000106 | JCB |

### 2026年9月1日以降は以下のカードをご使用ください

| カード番号 | タイプ |
| --- | --- |
| 4000000000000010 | Visa |
| 5200000000001021 | Mastercard |
| 3528000000000056 | JCB |
| 340000000001023 | Amex |
| 6029690000000002 | UnionPay |
| 36000000000008 | Diners/Discover |

## 認証成功（追加認証あり / 3DS フリクション）

パスワードチャレンジを伴う取引をテストできます。チャレンジを通過するには `123456` を入力してください。

| カード番号 | タイプ |
| --- | --- |
| 4100000000005000 | Visa |
| 5100000000005007 | Mastercard |
| 3528000000005006 | JCB |

### 2026年9月1日以降は以下のカードをご使用ください

チャレンジを通過するには `1234` を、チャレンジを失敗させるには `1111` を入力してください。

| カード番号 | タイプ |
| --- | --- |
| 4000000000000028 | Visa |
| 5100000000000010 | Mastercard |
| 3528000000000064 | JCB |
| 6029690000000028 | UnionPay |
| 36000000000248 | Diners/Discover |

## 認証失敗 (3DS フリクションレス失敗)

チャレンジなしで拒否される認証をテストできます。

| カード番号 | タイプ |
| --- | --- |
| 4100000000500000 | Visa |
| 5100000000500007 | Mastercard |
| 3528000000500006 | JCB |

### 2026年9月1日以降は以下のカードをご使用ください

| カード番号 | タイプ |
| --- | --- |
| 340000000001031 | Amex |
| 4000000000000044 | Visa |
| 5100000000000008 | Mastercard |
| 3528000000000122 | JCB |
| 6029690000000044 | UnionPay |
| 36000001000122 | Diners/Discover |

## 認証失敗（チャレンジでの失敗）

失敗するチャレンジパスワードをテストできます。失敗をシミュレートするには任意の数値を入力してください。

| カード番号 | タイプ |
| --- | --- |
| 4100000000300005 | Visa |
| 5100000000300002 | Mastercard |
| 3528000000300001 | JCB |

**2026年9月1日以降**は、「認証成功（追加認証あり）」セクションのテストカードを使用し、`1111` を入力して失敗をテストしてください。