サブスクリプション作成API

サブスクリプション支払いを処理

curl --request POST \
  --url https://api-dev.paymentoptions.com/api/v1/server-to-server-interface/subscription/payment \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "1000",
  "currency": "JPY",
  "card": {
    "cvc": "112",
    "expiry_month": "12",
    "expiry_year": "29",
    "name": "John Doe",
    "number": "4000000000001091"
  },
  "payment_method": {
    "type": "scheme",
    "store_payment_method": false
  },
  "merchant_id": "< Merchant ID >",
  "billing_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "postal_code": "1600022",
    "state": "Tokyo"
  },
  "subscription": {
    "plan_name": "Three weeks plan",
    "plan_desc": "Billed every two days",
    "cycle_type": "DAYS",
    "subscription_end_type": "CYCLE",
    "cycle_interval": 2,
    "max_cycle_count": 10,
    "has_trial_period": false,
    "has_discount": true,
    "discount_percentage": 10,
    "discount_duration": 2,
    "trial_period_duration_type": "DAYS",
    "trial_period_duration": 14
  },
  "merchant_txn_ref": "qwe",
  "customer_ip": "127.0.0.1",
  "return_url": {
    "webhook_url": "< Webhook url >",
    "success_url": "http://www.successurl.com/",
    "decline_url": "http://www.declineurl.com/"
  },
  "shipping_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "state": "Tokyo",
    "postal_code": "1600022"
  },
  "time_zone": "Asia/Kuala_Lumpur"
}
'

{
  "success": true,
  "status_code": 201,
  "is_live": false,
  "transaction_type": "CAPTURE",
  "gateway_response": {
    "version": "1",
    "type": "INFO",
    "message": "Payment Successful.",
    "code": "INFO0000"
  },
  "merchant_details": {
    "legal_name": "Beck's Coffee Shop Pvt. Ltd.",
    "mid": "JP00000472",
    "merchant_txn_ref": "qwe",
    "billing_details": {
      "billing_address": {
        "country": "JP",
        "email": "[email protected]",
        "phone_number": "8112345678",
        "address1": "1-2-3 Shinjuku",
        "city": "Shinjuku-ku",
        "state": "Tokyo",
        "postal_code": "1600022"
      },
      "shipping_address": {
        "country": "JP",
        "email": "[email protected]",
        "phone_number": "8112345678",
        "address1": "1-2-3 Shinjuku",
        "city": "Shinjuku-ku",
        "state": "Tokyo",
        "postal_code": "1600022"
      }
    },
    "device_details": {
      "visited_ip": "127.0.0.1",
      "merchant_ip": "127.0.0.1",
      "customer_ip": "127.0.0.1"
    }
  },
  "payment_details": {
    "amount": 900,
    "response_code": 0,
    "auth_code": "175438",
    "currency": "JPY",
    "payment_method": "VISA_DEBIT-SSL",
    "scheme": "VISA",
    "card": {
      "name": "John Doe",
      "number": "4000000000001091",
      "exp_month": "12",
      "exp_year": "29"
    },
    "additional_data": {
      "payment_data_source": {
        "type": "card"
      }
    }
  },
  "transaction_details": {
    "id": "359f39bd-673a-47b3-b9ec-cbd6cd313b8e",
    "ref": 74860,
    "timestamp": "2024-11-26T01:31:29.000Z",
    "merchant_txn_ref": "qwe",
    "stored_payment_method_id": null
  },
  "risk-details": {
    "risk_score": null
  },
  "subscription_details": {
    "id": "664dc930-88bd-4696-8807-5e0f1fedba0b",
    "type": "CYCLE",
    "max_cycle_count": 10,
    "status": "ACTIVE",
    "completed_payment_cycle": 1,
    "next_payment_date": "2024-11-28T01:31:29.154Z",
    "next_payment_cycle": 2,
    "subscription_plan_details": {
      "name": "Three weeks plan",
      "desc": "Billed every two days",
      "billing_cycle_type": "DAYS",
      "billing_cycle_interval": 2,
      "amount": 1000,
      "ccy": "JPY",
      "trial_period_duration": "",
      "trial_period_duration_type": "NONE",
      "plan_discount_percentage": 10,
      "plan_discount_duration": 2
    }
  }
}

POST

api

server-to-server-interface

subscription

payment

サブスクリプション支払いを処理

curl --request POST \
  --url https://api-dev.paymentoptions.com/api/v1/server-to-server-interface/subscription/payment \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "1000",
  "currency": "JPY",
  "card": {
    "cvc": "112",
    "expiry_month": "12",
    "expiry_year": "29",
    "name": "John Doe",
    "number": "4000000000001091"
  },
  "payment_method": {
    "type": "scheme",
    "store_payment_method": false
  },
  "merchant_id": "< Merchant ID >",
  "billing_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "postal_code": "1600022",
    "state": "Tokyo"
  },
  "subscription": {
    "plan_name": "Three weeks plan",
    "plan_desc": "Billed every two days",
    "cycle_type": "DAYS",
    "subscription_end_type": "CYCLE",
    "cycle_interval": 2,
    "max_cycle_count": 10,
    "has_trial_period": false,
    "has_discount": true,
    "discount_percentage": 10,
    "discount_duration": 2,
    "trial_period_duration_type": "DAYS",
    "trial_period_duration": 14
  },
  "merchant_txn_ref": "qwe",
  "customer_ip": "127.0.0.1",
  "return_url": {
    "webhook_url": "< Webhook url >",
    "success_url": "http://www.successurl.com/",
    "decline_url": "http://www.declineurl.com/"
  },
  "shipping_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "state": "Tokyo",
    "postal_code": "1600022"
  },
  "time_zone": "Asia/Kuala_Lumpur"
}
'

{
  "success": true,
  "status_code": 201,
  "is_live": false,
  "transaction_type": "CAPTURE",
  "gateway_response": {
    "version": "1",
    "type": "INFO",
    "message": "Payment Successful.",
    "code": "INFO0000"
  },
  "merchant_details": {
    "legal_name": "Beck's Coffee Shop Pvt. Ltd.",
    "mid": "JP00000472",
    "merchant_txn_ref": "qwe",
    "billing_details": {
      "billing_address": {
        "country": "JP",
        "email": "[email protected]",
        "phone_number": "8112345678",
        "address1": "1-2-3 Shinjuku",
        "city": "Shinjuku-ku",
        "state": "Tokyo",
        "postal_code": "1600022"
      },
      "shipping_address": {
        "country": "JP",
        "email": "[email protected]",
        "phone_number": "8112345678",
        "address1": "1-2-3 Shinjuku",
        "city": "Shinjuku-ku",
        "state": "Tokyo",
        "postal_code": "1600022"
      }
    },
    "device_details": {
      "visited_ip": "127.0.0.1",
      "merchant_ip": "127.0.0.1",
      "customer_ip": "127.0.0.1"
    }
  },
  "payment_details": {
    "amount": 900,
    "response_code": 0,
    "auth_code": "175438",
    "currency": "JPY",
    "payment_method": "VISA_DEBIT-SSL",
    "scheme": "VISA",
    "card": {
      "name": "John Doe",
      "number": "4000000000001091",
      "exp_month": "12",
      "exp_year": "29"
    },
    "additional_data": {
      "payment_data_source": {
        "type": "card"
      }
    }
  },
  "transaction_details": {
    "id": "359f39bd-673a-47b3-b9ec-cbd6cd313b8e",
    "ref": 74860,
    "timestamp": "2024-11-26T01:31:29.000Z",
    "merchant_txn_ref": "qwe",
    "stored_payment_method_id": null
  },
  "risk-details": {
    "risk_score": null
  },
  "subscription_details": {
    "id": "664dc930-88bd-4696-8807-5e0f1fedba0b",
    "type": "CYCLE",
    "max_cycle_count": 10,
    "status": "ACTIVE",
    "completed_payment_cycle": 1,
    "next_payment_date": "2024-11-28T01:31:29.154Z",
    "next_payment_cycle": 2,
    "subscription_plan_details": {
      "name": "Three weeks plan",
      "desc": "Billed every two days",
      "billing_cycle_type": "DAYS",
      "billing_cycle_interval": 2,
      "amount": 1000,
      "ccy": "JPY",
      "trial_period_duration": "",
      "trial_period_duration_type": "NONE",
      "plan_discount_percentage": 10,
      "plan_discount_duration": 2
    }
  }
}

サブスクリプション作成のリクエスト例

"subscription": {
        "plan_name": "<string>",
        "plan_desc": "<string>",
        "cycle_type": "<DAYS/WEEKLY/MONTHLY>",
        "subscription_end_type": "CYCLE",
        "cycle_interval": <int>,
        "max_cycle_count": <int>,
        "has_trial_period": <boolean>,
        "trial_period_duration_type": "DAYS",
        "trial_period_duration": <int>,
        "has_discount": <boolean>,
        "discount_percentage": <int>,
        "discount_duration": <int>
    }

重要なポイント

サブスクリプション作成

このAPIは、サブスクリプションプランの設定を可能にし、自動的な定期支払いを提供します。さまざまな請求サイクルや割引、試用期間などの柔軟な設定をサポートしています。

サブスクリプション設定

加盟店は、カスタムプランを定義できます。これには、プラン名と説明が含まれます。
サイクルタイプ：請求は日、週、月などに基づいて行えます。
サイクル間隔：請求の頻度を定義します（例：2日ごと、毎月）。
最大サイクル数：請求サイクルの最大数を設定します。
試用期間：サブスクリプション開始前に試用期間を提供するオプション。
割引：定められた請求サイクル数に対して割引を適用する機能。

フローダイアグラム

APIパラメータ

Authorizations

Authorization

string

header

required

認証用のAPIキー。フォーマット：「Basic YOUR_API_KEY_HERE」

x-api-key

string

header

required

x-api-key専用のAPIキー。

Body

application/json

サブスクリプション支払いを処理するためのペイロード。

amount

string

required

取引金額。

Maximum string length: 15

Example:

"1000"

currency

string

required

取引のISO通貨コード（例：JPY）。

Maximum string length: 3

Example:

"JPY"

card

object

required

支払いに使用するカードの詳細。

表示子属性

card.cvc

string

required

カードのセキュリティコード。

Maximum string length: 4

Example:

"112"

card.expiry_month

string

required

カードの有効期限（月）。

Maximum string length: 2

Example:

"12"

card.expiry_year

string

required

カードの有効期限の年（例：29 または 2029 年）。

Maximum string length: 4

Example:

"29"

card.name

string

required

カード所有者の名前。

Maximum string length: 255

Example:

"John Doe"

card.number

string

required

カード番号。

Maximum string length: 16

Example:

"4000000000001091"

payment_method

object

required

決済方法の詳細。

表示子属性

payment_method.type

string

required

決済方法の種類（例：カード決済の場合は 'scheme'）。

Maximum string length: 128

Example:

"scheme"

payment_method.store_payment_method

boolean

required

将来の取引のために支払い方法を保存するかどうか。

Example:

false

merchant_id

string

required

加盟店の一意識別子。

Maximum string length: 128

Example:

"< Merchant ID >"

billing_address

object

required

カード所有者の請求先住所の詳細。

表示子属性

billing_address.country

string

required

請求先の国コード（ISO 3166-1 alpha-2）。

Maximum string length: 2

Example:

"JP"

billing_address.email

string

required

請求先メールアドレス。

Maximum string length: 45

Example:

"[email protected]"

billing_address.phone_number

string

required

請求先電話番号。

Maximum string length: 20

Example:

"8112345678"

billing_address.address1

string

required

請求先住所。

Maximum string length: 199

Example:

"1-2-3 Shinjuku"

billing_address.city

string

required

請求先市区町村。

Maximum string length: 65

Example:

"Shinjuku-ku"

billing_address.postal_code

string

required

請求先郵便番号。

Maximum string length: 45

Example:

"1600022"

billing_address.state

string

請求先の州（任意）。

Maximum string length: 65

Example:

"Tokyo"

subscription

object

required

処理されるサブスクリプションの詳細。

表示子属性

subscription.plan_name

string

required

サブスクリプションプラン名。

Maximum string length: 100

Example:

"Three weeks plan"

subscription.plan_desc

string

required

サブスクリプションプランの説明。

Maximum string length: 200

Example:

"Billed every two days"

subscription.cycle_type

string

required

サブスクリプションのサイクルタイプ (e.g., DAYS, WEEKLY or MONTHLY)。

Example:

"DAYS"

subscription.subscription_end_type

string

required

サブスクリプションの終了タイプ（例：CYCLE）。

Example:

"CYCLE"

subscription.cycle_interval

integer

required

請求サイクル間の間隔。

Example:

2

subscription.max_cycle_count

integer

required

最大請求サイクル数。

Example:

10

subscription.has_trial_period

boolean

required

サブスクリプションに試用期間が含まれるかどうかを示します。

Example:

false

subscription.has_discount

boolean

required

サブスクリプションに割引が適用されているかどうかを示します。

Example:

true

subscription.discount_percentage

number

required

サブスクリプションに適用される割引率。

Example:

10

subscription.discount_duration

integer

required

請求サイクル単位での割引の期間。

Example:

2

subscription.trial_period_duration_type

string

試用期間の期間タイプ（例：DAYS, MONTHS）。

Example:

"DAYS"

subscription.trial_period_duration

integer

試用期間の長さ。

Example:

14

merchant_txn_ref

string

一意の決済取引参照ID。

Maximum string length: 45

Example:

"qwe"

customer_ip

string

取引を開始した顧客のIPアドレス。

Maximum string length: 45

Example:

"127.0.0.1"

return_url

object

リターンURLを含むJSONオブジェクト。（3DS取引では必須）

表示子属性

return_url.webhook_url

string

Webhook通知のためのURL。

Maximum string length: 255

Example:

"< Webhook url >"

return_url.success_url

string

取引成功後のリダイレクトURL。

Maximum string length: 255

Example:

"http://www.successurl.com/"

return_url.decline_url

string

取引が拒否された場合のリダイレクトURL。

Maximum string length: 255

Example:

"http://www.declineurl.com/"

shipping_address

object

カード所有者の配送先住所の詳細。

表示子属性

shipping_address.country

string

配送先の国コード（ISO 3166-1 alpha-2）。

Maximum string length: 2

Example:

"JP"

shipping_address.email

string

配送先メールアドレス。

Maximum string length: 45

Example:

"[email protected]"

shipping_address.phone_number

string

配送先電話番号。

Maximum string length: 20

Example:

"8112345678"

shipping_address.address1

string

配送先住所。

Maximum string length: 199

Example:

"1-2-3 Shinjuku"

shipping_address.city

string

配送先市区町村。

Maximum string length: 65

Example:

"Shinjuku-ku"

shipping_address.state

string

配送先の州（任意）。

Maximum string length: 65

Example:

"Tokyo"

shipping_address.postal_code

string

配送先郵便番号。

Maximum string length: 45

Example:

"1600022"

time_zone

string

取引のタイムゾーン。

Maximum string length: 128

Example:

"Asia/Kuala_Lumpur"

Response

201 - application/json

サブスクリプション支払いが正常に処理されました。

success

boolean

取引が成功したかどうかを示します。

Example:

true

status_code

integer

取引のHTTPステータスコード。

Example:

201

is_live

boolean

取引が本番環境のものかテスト環境のものかを示します。

Example:

false

transaction_type

string

実行された取引の種類（例：CAPTURE）。

Example:

"CAPTURE"

gateway_response

object

決済ゲートウェイからの応答。

表示子属性

gateway_response.version

string

ゲートウェイ応答のバージョン。

Example:

"1"

gateway_response.type

string

ゲートウェイ応答のタイプ。

Example:

"INFO"

gateway_response.message

string

ゲートウェイからのメッセージ。

Example:

"Payment Successful."

gateway_response.code

string

ゲートウェイからの応答コード。

Example:

"INFO0000"

merchant_details

object

加盟店に関する詳細情報。

表示子属性

merchant_details.legal_name

string

加盟店の正式名称。

Example:

"Beck's Coffee Shop Pvt. Ltd."

merchant_details.mid

string

加盟店ID。

Example:

"JP00000472"

merchant_details.merchant_txn_ref

string

加盟店の取引参照ID。

Example:

"qwe"

merchant_details.billing_details

object

請求先および配送先住所の詳細。

表示子属性

merchant_details.billing_details.billing_address

object

加盟店の請求先住所。

表示子属性

merchant_details.billing_details.billing_address.country

string

国コード。

Example:

"JP"

merchant_details.billing_details.billing_address.email

string

請求先メールアドレス。

Example:

"[email protected]"

merchant_details.billing_details.billing_address.phone_number

string

請求先電話番号。

Example:

"8112345678"

merchant_details.billing_details.billing_address.address1

string

請求先住所。

Example:

"1-2-3 Shinjuku"

merchant_details.billing_details.billing_address.city

string

請求先の市区町村。

Example:

"Shinjuku-ku"

merchant_details.billing_details.billing_address.state

string

請求先の都道府県。

Example:

"Tokyo"

merchant_details.billing_details.billing_address.postal_code

string

請求先の郵便番号。

Example:

"1600022"

merchant_details.billing_details.shipping_address

object

加盟店の配送先住所。

表示子属性

merchant_details.billing_details.shipping_address.country

string

国コード。

Example:

"JP"

merchant_details.billing_details.shipping_address.email

string

配送先メールアドレス。

Example:

"[email protected]"

merchant_details.billing_details.shipping_address.phone_number

string

配送先電話番号。

Example:

"8112345678"

merchant_details.billing_details.shipping_address.address1

string

配送先住所。

Example:

"1-2-3 Shinjuku"

merchant_details.billing_details.shipping_address.city

string

配送先の市区町村。

Example:

"Shinjuku-ku"

merchant_details.billing_details.shipping_address.state

string

配送先の都道府県。

Example:

"Tokyo"

merchant_details.billing_details.shipping_address.postal_code

string

配送先の郵便番号。

Example:

"1600022"

merchant_details.device_details

object

顧客のデバイス詳細。

表示子属性

merchant_details.device_details.visited_ip

string

決済ページのIPアドレス。

Example:

"127.0.0.1"

merchant_details.device_details.merchant_ip

string

加盟店のIPアドレスです。

Example:

"127.0.0.1"

merchant_details.device_details.customer_ip

string

カード所有者のIPアドレス。

Example:

"127.0.0.1"

payment_details

object

決済取引の詳細。

表示子属性

payment_details.amount

number

取引金額。

Example:

900

payment_details.response_code

integer

アクワイアラーからの応答コード。

Example:

0

payment_details.auth_code

string

アクワイアラーからの認証コード。

Example:

"175438"

payment_details.currency

string

取引通貨。

Example:

"JPY"

payment_details.payment_method

string

使用された支払い方法。

Example:

"VISA_DEBIT-SSL"

payment_details.scheme

string

使用されたカードスキーム。

Example:

"VISA"

payment_details.card

object

使用されたカードの詳細。

表示子属性

payment_details.card.name

string

カード所有者の名前。

Example:

"John Doe"

payment_details.card.number

string

マスクされたカード番号。

Example:

"4000000000001091"

payment_details.card.exp_month

string

カードの有効期限（月）。

Example:

"12"

payment_details.card.exp_year

string

カードの有効期限（年）。

Example:

"29"

payment_details.additional_data

object

追加の決済関連データ。

表示子属性

payment_details.additional_data.payment_data_source

object

決済のデータソース。

表示子属性

payment_details.additional_data.payment_data_source.type

string

決済データソースの種類。

Example:

"card"

transaction_details

object

取引の詳細。

表示子属性

transaction_details.id

string

取引ID。

Example:

"359f39bd-673a-47b3-b9ec-cbd6cd313b8e"

transaction_details.ref

integer

取引参照番号。

Example:

74860

transaction_details.timestamp

string<date-time>

取引のタイムスタンプ。

Example:

"2024-11-26T01:31:29.000Z"

transaction_details.merchant_txn_ref

string

加盟店の取引参照ID。

Example:

"qwe"

transaction_details.stored_payment_method_id

string | null

保存された決済方法ID（該当する場合）。

Example:

null

risk-details

object

リスク評価の詳細。

表示子属性

risk-details.risk_score

number | null

取引のリスクスコア。

Example:

null

subscription_details

object

サブスクリプションの詳細。

表示子属性

subscription_details.id

string

サブスクリプションID。

Example:

"664dc930-88bd-4696-8807-5e0f1fedba0b"

subscription_details.type

string

サブスクリプションの種類（例：CYCLE）。

Example:

"CYCLE"

subscription_details.max_cycle_count

integer

最大請求サイクル数。

Example:

10

subscription_details.status

string

サブスクリプションのステータス。

Example:

"ACTIVE"

subscription_details.completed_payment_cycle

integer

完了した支払いサイクルの数。

Example:

1

subscription_details.next_payment_date

string<date-time>

次回の支払い日。

Example:

"2024-11-28T01:31:29.154Z"

subscription_details.next_payment_cycle

integer

次の支払いサイクル番号。

Example:

2

subscription_details.subscription_plan_details

object

サブスクリプションプランの詳細。

表示子属性

subscription_details.subscription_plan_details.name

string

サブスクリプションプランの名前。

Example:

"Three weeks plan"

subscription_details.subscription_plan_details.desc

string

サブスクリプションプランの説明。

Example:

"Billed every two days"

subscription_details.subscription_plan_details.billing_cycle_type

string

請求サイクルの種類（例：DAYS、MONTHS）。

Example:

"DAYS"

subscription_details.subscription_plan_details.billing_cycle_interval

integer

請求サイクル間の間隔。

Example:

2

subscription_details.subscription_plan_details.amount

number

各請求サイクルの金額。

Example:

1000

subscription_details.subscription_plan_details.ccy

string

サブスクリプションの通貨コード。

Example:

"JPY"

subscription_details.subscription_plan_details.trial_period_duration

string | null

試用期間の期間。

Example:

""

subscription_details.subscription_plan_details.trial_period_duration_type

string

試用期間の種類。

Example:

"NONE"

subscription_details.subscription_plan_details.plan_discount_percentage

number

サブスクリプションプランに適用される割引率。

Example:

10

subscription_details.subscription_plan_details.plan_discount_duration

integer

割引の適用期間（請求サイクル数）。

Example:

2

トークン使用API サブスクリプションキャンセルAPI

⌘I

入門

APIエンドポイント

エラーとレスポンス

ウェブフック

サブスクリプション作成のリクエスト例

重要なポイント

サブスクリプション作成

サブスクリプション設定

フローダイアグラム

APIパラメータ

Authorizations

Body

Response

入門

APIエンドポイント

エラーとレスポンス

ウェブフック

​サブスクリプション作成のリクエスト例

​重要なポイント

​サブスクリプション作成

​サブスクリプション設定

​フローダイアグラム

​APIパラメータ

Authorizations

Body

Response

サブスクリプション作成のリクエスト例

重要なポイント

サブスクリプション作成

サブスクリプション設定

フローダイアグラム

APIパラメータ