---
title: "セッションなしで３Dセキュアー"
description: "ペイメントを直接作成する際の3DSガイド"
url: "https://docs.komoju.com/ja/docs/integration-guides/payments-api-3ds"
source_url: "https://docs.komoju.com/ja/docs/integration-guides/payments-api-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上で処理するので対応の必要はありません。）

# Secure Token APIの流れ

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

![](https://files.readme.io/3bc612f-scratch.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` | 数値 | 数値 |
| `currency` | 文字列 | アルファベット3文字の通貨コード |
| `return_url` | 文字列 | ユーザーが認証を完了した後にリダイレクトされるURL |
| `payment_details[type]` | 文字列 | "credit_card" |
| `payment_details[email]` | 文字列 | ペイメント受領時に送信するメールアドレス。 |
| `payment_details[number]` | 数値 | クレジットカード番号 |
| `payment_details[month]` | 数値 | 有効期限月 |
| `payment_details[year]` | 数値 | 有効期限年 |
| `payment_details[verification_value]` | 数値 | CCV セキュリティ番号 |
| `payment_details[name]` | 文字列 | クレジットカードの所有者名（アルファベット） |

| リクエストパラメータ | タイプ | 詳細 |
| --- | --- | --- |
| `id` | 文字列 | 生成されたSecure TokenのID |
| `verification_status` | 文字列 | `OK`, `NEEDS_VERIFY`, `SKIPPED`, or `ERRORED` |
| `authentication_url` | 文字列 | 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 モードで挙動を確認したい場合、下記のテスト用カード番号およびテスト用顧客情報を利用してください。

テスト用カードで推奨されるテスト用顧客情報は下記の通りです。

- `payment_details[name]` : Test Card
- `payment_details[month]` : 08
- `payment_details[year]` : 2025

## 認証成功

3D Secure 2.0の成功フローをテストできます。

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

## 認証成功（追加認証あり）

3D Secure 2.0認証における、追加認証（チャレンジ）フローをテストできます。パスワード入力画面では `123456` と入力することで、認証成功となります。

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

## 認証失敗

3D Secure 2.0認証の失敗フローをテストできます。`authentication_url` にアクセス後、追加認証なしで認証失敗となります。

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

## 認証失敗（追加認証あり）

3D Secure 2.0認証の追加認証フローにおける、追加認証の失敗をテストできます。パスワード入力画面で `111111` と入力することで、認証失敗となります。

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