全てのイベントを発生させる方法まとめ

WebPayでは、オブジェクトに起こったことを時系列で管理するために、イベントオブジェクトを提供しています。 イベントが発生した時にはWebhookによる通知も取得できるので、 定期課金による課金の作成などWebPay上で自動的に起こった変化を簡単に知ることができます。

イベントの処理やWebhookを実装する場合はすべてのイベントをテストしたいものですが、 一部の種類のイベントはどうやったらテスト環境で発生するか、わかりにくいです。 そこで、この記事では今実装されているすべてのイベントを発生させるためのテクニックをお教えします。

特に定期課金オブジェクトをご利用の方に有益な情報です。

以下すべてのイベントの例を掲載していますが、本記事作成時点であり、今後APIの更新によりフィールドが追加される場合があります。 自動テスト用のサンプルレスポンスに使う場合は、必ずテスト環境にリクエストを行い、最新のレスポンス内容を確認してご利用ください。

charge.succeeded

新規に課金の作成に成功した際に発生します。 テスト用のカード番号を指定して、課金作成APIかテスト環境のダッシュボードから課金を作成することで発生します。

1
2
3
4
5
6
7
8
9
10
curl "https://api.webpay.jp/v1/charges" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=400" \
    -d "currency=jpy" \
    -d "card[number]=4242-4242-4242-4242" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=テストの課金"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "id": "evt_35iaYj0ymeme8AU",
  "object": "event",
  "livemode": false,
  "type": "charge.succeeded",
  "created": 1412350884,
  "data": {
    "object": {
      "id": "ch_35iaUbbVqelA1iF",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "テストの課金",
      "amount": 400,
      "amount_refunded": 0,
      "customer": null,
      "recursion": null,
      "created": 1412350883,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2014,
        "exp_month": 11,
        "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
        "name": "KEI KUBO",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "4242"
      },
      "captured": true,
      "expire_time": null,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 13,
          "created": 1412350883
        }
      ]
    }
  },
  "pending_webhooks": 0
}

charge.failed

課金の作成が失敗した際に発生します。 課金時にエラーになるテスト用のカード番号を指定して課金を作成すると発生します。

カードの情報としては妥当であるものの、カード所有者やカードを発行している会社の都合や判断によりエラーとなる場合に発生するもので、 単純に有効期限の年が現在より古いなど、カードの情報として妥当でない場合には課金の作成を試行しないためこのイベントは発生しません。

1
2
3
4
5
6
7
8
9
10
curl "https://api.webpay.jp/v1/charges" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=400" \
    -d "currency=jpy" \
    -d "card[number]=4000000000080202" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=エラーになる課金"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "id": "evt_35i4zX6GUfCC9P4",
  "object": "event",
  "livemode": false,
  "type": "charge.failed",
  "created": 1412351300,
  "data": {
    "object": {
      "id": "ch_35i4zX5hifef7nn",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "エラーになる課金",
      "amount": 400,
      "amount_refunded": 0,
      "customer": null,
      "recursion": null,
      "created": 1412351300,
      "paid": false,
      "refunded": false,
      "failure_message": "This card cannot be used. Contact card issuer to determine reason or choose a different card.",
      "card": {
        "object": "card",
        "exp_year": 2014,
        "exp_month": 11,
        "fingerprint": "2e326d50e5e59ce92fc3e3084b99f7e3c33317f9",
        "name": "KEI KUBO",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "0202"
      },
      "captured": false,
      "expire_time": null,
      "fees": [

      ]
    }
  },
  "pending_webhooks": 0
}

charge.refunded

一部払い戻しも含めて、課金の払い戻し処理が行われた際に発生します。 仮売上が実売上化されることなく、失効した場合にも発生します。 最初に作成した課金を払い戻して発生させます。

1
2
3
curl "https://api.webpay.jp/v1/charges/ch_35iaUbbVqelA1iF/refund" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=200"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "id": "evt_35i3YO5WO1R8gHm",
  "object": "event",
  "livemode": false,
  "type": "charge.refunded",
  "created": 1412351547,
  "data": {
    "object": {
      "id": "ch_35iaUbbVqelA1iF",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "テストの課金",
      "amount": 400,
      "amount_refunded": 200,
      "customer": null,
      "recursion": null,
      "created": 1412350883,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2014,
        "exp_month": 11,
        "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
        "name": "KEI KUBO",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "4242"
      },
      "captured": true,
      "expire_time": null,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 13,
          "created": 1412350883
        },
        {
          "object": "fee",
          "transaction_type": "refund",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": -13,
          "created": 1412351547
        },
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 7,
          "created": 1412351547
        }
      ]
    }
  },
  "pending_webhooks": 0
}

charge.captured

仮売上が実売上化された際に発生します。 テスト用カードを指定して仮売上を作成し、その後実売上化します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl "https://api.webpay.jp/v1/charges" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=400" \
    -d "currency=jpy" \
    -d "card[number]=4242-4242-4242-4242" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=仮売上" \
    -d "capture=false"
curl "https://api.webpay.jp/v1/charges/ch_35i7vF9vB17p1YL/capture" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -X POST
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "id": "evt_35i37a4ay4Id91Q",
  "object": "event",
  "livemode": false,
  "type": "charge.captured",
  "created": 1412352046,
  "data": {
    "object": {
      "id": "ch_35i7vF9vB17p1YL",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "仮売上",
      "amount": 400,
      "amount_refunded": 0,
      "customer": null,
      "recursion": null,
      "created": 1412351856,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2014,
        "exp_month": 11,
        "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
        "name": "KEI KUBO",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "4242"
      },
      "captured": true,
      "expire_time": 1412956656,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 2.69,
          "amount": 11,
          "created": 1412352046
        }
      ]
    }
  },
  "pending_webhooks": 0
}

customer.created

新規の顧客が作成された際に発生します。

1
2
3
curl "https://api.webpay.jp/v1/customers" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -X POST
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "evt_35ibaM56LaI61iG",
  "object": "event",
  "livemode": false,
  "type": "customer.created",
  "created": 1412352167,
  "data": {
    "object": {
      "id": "cus_35ibaMgyG3TT1vU",
      "object": "customer",
      "livemode": false,
      "created": 1412352167,
      "email": null,
      "description": null,
      "active_card": null,
      "recursions": [

      ]
    }
  },
  "pending_webhooks": 0
}

customer.updated

顧客が更新された際に発生します。 前項で作成した顧客のメールアドレスを変更します。

1
2
3
curl "https://api.webpay.jp/v1/customers/cus_35ibaMgyG3TT1vU" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "email=test@example.com"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "id": "evt_35i2QF3kkecS8yF",
  "object": "event",
  "livemode": false,
  "type": "customer.updated",
  "created": 1412352298,
  "data": {
    "object": {
      "id": "cus_35ibaMgyG3TT1vU",
      "object": "customer",
      "livemode": false,
      "created": 1412352167,
      "email": "test@example.com",
      "description": null,
      "active_card": null,
      "recursions": [

      ]
    },
    "previous_attributes": {
      "email": null
    }
  },
  "pending_webhooks": 0
}

customer.deleted

顧客が削除された際に発生します。 上の顧客を削除します。

1
2
3
curl "https://api.webpay.jp/v1/customers/cus_35ibaMgyG3TT1vU" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -X DELETE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "evt_35i8nn3zf5Ef7b7",
  "object": "event",
  "livemode": false,
  "type": "customer.deleted",
  "created": 1412352381,
  "data": {
    "object": {
      "id": "cus_35ibaMgyG3TT1vU",
      "object": "customer",
      "livemode": false,
      "created": 1412352167,
      "email": "test@example.com",
      "description": null,
      "active_card": null,
      "recursions": [

      ]
    }
  },
  "pending_webhooks": 0
}

recursion.created

定期課金が作成された際に発生します。 まず有効なカード情報を持った顧客を作成し、それに紐づく定期課金を作ります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl "https://api.webpay.jp/v1/customers" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "card[number]=4242-4242-4242-4242" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=定期課金顧客"
curl "https://api.webpay.jp/v1/recursions" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=150" \
    -d "currency=jpy" \
    -d "customer=cus_35i5fk8CG0PNa9A" \
    -d "period=month" \
    -d "description=定期課金のテスト"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "evt_35ia2C1zN6AwdMM",
  "object": "event",
  "livemode": false,
  "type": "recursion.created",
  "created": 1412352662,
  "data": {
    "object": {
      "id": "rec_35ia2Cfpa0lYchv",
      "object": "recursion",
      "livemode": false,
      "created": 1412352662,
      "amount": 150,
      "currency": "jpy",
      "period": "month",
      "description": "定期課金のテスト",
      "customer": "cus_35i5fk8CG0PNa9A",
      "last_executed": null,
      "next_scheduled": 1412352662,
      "status": "active"
    }
  },
  "pending_webhooks": 0
}

recursion.succeeded

定期課金による課金が成功した際に発生します。 上で定期課金を作成した時に最初の課金が実行されますので、すでにこのイベントも発生しています。

なお、定期課金ではなく作成された課金の詳細が知りたい場合、charge,succeededイベントのほうを処理し、data.object.recursionのidを使って定期課金との照合を行います。 webpay-closetにおける実装例も参考にしてください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "evt_35ia2Ca0Wfz3dMa",
  "object": "event",
  "livemode": false,
  "type": "recursion.succeeded",
  "created": 1412352662,
  "data": {
    "object": {
      "id": "rec_35ia2Cfpa0lYchv",
      "object": "recursion",
      "livemode": false,
      "created": 1412352662,
      "amount": 150,
      "currency": "jpy",
      "period": "month",
      "description": "定期課金のテスト",
      "customer": "cus_35i5fk8CG0PNa9A",
      "last_executed": 1412352662,
      "next_scheduled": 1415031062,
      "status": "active"
    }
  },
  "pending_webhooks": 0
}

recursion.failed

定期課金による課金が失敗した際に発生します。 「トークン作成時や顧客作成時にはエラーにならず、課金する時にエラーを発生させる」カード番号を指定することで意図的に初回課金を失敗させると簡単です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl "https://api.webpay.jp/v1/customers" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "card[number]=4000-0000-0008-0202" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=定期課金を失敗させる顧客"
curl "https://api.webpay.jp/v1/recursions" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "amount=150" \
    -d "currency=jpy" \
    -d "customer=cus_35i8UrfEUgbR3AM" \
    -d "period=month" \
    -d "description=定期課金の失敗テスト"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "evt_35iaf14Ndb2adSW",
  "object": "event",
  "livemode": false,
  "type": "recursion.failed",
  "created": 1412352921,
  "data": {
    "object": {
      "id": "rec_35iaf13oP7DB8U4",
      "object": "recursion",
      "livemode": false,
      "created": 1412352921,
      "amount": 150,
      "currency": "jpy",
      "period": "month",
      "description": "定期課金の失敗テスト",
      "customer": "cus_35i8UrfEUgbR3AM",
      "last_executed": 1412352921,
      "next_scheduled": null,
      "status": "suspended"
    }
  },
  "pending_webhooks": 0
}

recursion.resumed

定期課金が再開された際に発生します。 上で作成した失敗した定期課金を、正常に課金出来る状態に戻してからresumeします。 紐付いた顧客のカード番号を失敗しないものに戻さないと、再開時にエラーになります。

1
2
3
4
5
6
7
8
9
10
11
curl "https://api.webpay.jp/v1/customers/cus_35i8UrfEUgbR3AM" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -d "card[number]=4242-4242-4242-4242" \
    -d "card[exp_month]=11" \
    -d "card[exp_year]=2014" \
    -d "card[cvc]=123" \
    -d "card[name]=KEI KUBO" \
    -d "description=定期課金を失敗させる顧客(修正済み)"
curl "https://api.webpay.jp/v1/recursions/rec_35iaf13oP7DB8U4/resume" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -X POST
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "evt_35i3EhdNO7ScaK8",
  "object": "event",
  "livemode": false,
  "type": "recursion.resumed",
  "created": 1412353334,
  "data": {
    "object": {
      "id": "rec_35iaf13oP7DB8U4",
      "object": "recursion",
      "livemode": false,
      "created": 1412352921,
      "amount": 150,
      "currency": "jpy",
      "period": "month",
      "description": "定期課金の失敗テスト",
      "customer": "cus_35i8UrfEUgbR3AM",
      "last_executed": 1412352921,
      "next_scheduled": 1415031321,
      "status": "active"
    }
  },
  "pending_webhooks": 0
}

recursion.deleted

定期課金が削除された際に発生します。 上で作成した定期課金を削除します。

1
2
3
curl "https://api.webpay.jp/v1/recursions/rec_35iaf13oP7DB8U4" \
    -u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
    -X DELETE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "evt_35i96R8UvbDegjW",
  "object": "event",
  "livemode": false,
  "type": "recursion.deleted",
  "created": 1412353416,
  "data": {
    "object": {
      "id": "rec_35iaf13oP7DB8U4",
      "object": "recursion",
      "livemode": false,
      "created": 1412352921,
      "amount": 150,
      "currency": "jpy",
      "period": "month",
      "description": "定期課金の失敗テスト",
      "customer": "cus_35i8UrfEUgbR3AM",
      "last_executed": 1412352921,
      "next_scheduled": 1415031321,
      "status": "active"
    }
  },
  "pending_webhooks": 0
}

account.application.deauthorized

将来の利用のために予約されています。 まだテストできません。

ping

設定画面下部のWebhookの設定欄から「テストのイベントを発行」したときに送信されます。 Webhookを設定する際には、まずはこのイベントを使って疎通確認を行ってください。

おわりに

定期課金のイベントや遷移をどうやってテストしたらよいのか、というのはしばしばご質問をいただく項目でした。 ほかのオブジェクトに比べ、定期課金はテスト環境で自由に変更することが難しく、しかも期間が1ヶ月などと長いので、テストしにくいと思われがちです。 じつは、今回紹介したように、テスト用カード番号を利用することで即時にすべてのイベントを発生させることができます。

テスト用カード番号はエラーレスポンスのテストでも大変役に立つので、ぜひ覚えておいてください。 イベントやWebhookについて疑問がありましたら、フォーラムにてお気軽にお尋ねください。