create-pricing-intent

価格設定インテントの作成

バージョンの確認（最初に実行）

何かを告知したり、フローを開始したりする前に、このスキルが最新であることを確認してください。

1. 上記のフロントマターにある metadata.version フィールドから、このスキルのバージョンを読み取ります。
2. 公開されているコピーを取得し、その metadata.version を読み取ります。 https://raw.githubusercontent.com/payroc/skills/main/plugins/payroc/boarding/skills/create-pricing-intent/SKILL.md
3. セマンティックバージョンとして2つを比較します。

   • このバージョン >= 公開バージョン → 何も伝えず、そのまま続行します。（開発者が未公開の新しいバージョンを実行している場合は、問題ありません。）

   • このバージョン < 公開バージョン → 開発者に次のように伝えます。

     ⚠️ このスキルの新しいバージョン（v<published>）が公開されています。現在実行中のバージョンは v<current> です。最良の結果を得るため、アップグレードをおすすめします。

     現在のバージョンで続行するか、いったん停止してアップグレードするかを尋ね、回答に従います。

   • 取得できなかった場合（オフライン、ネットワークエラー、404）→ バージョンを確認できなかったことを簡潔に伝え、続行します。

---

価格設定インテントは、再利用可能な加盟店処理契約（MPA）テンプレートです。手数料を一度定義し、Payroc に審査・承認してもらった後、加盟店登録時に処理アカウントへその id を割り当てます。階層が深い価格設定契約の代わりに、短い参照を使用できます。

POST https://api.payroc.com/v1/pricing-intents でテンプレートを作成します。Payroc は id と pendingReview の status を返します。active になった後は、create-merchant-platform から参照できます（下記の「ID の使用」を参照）。

価格設定インテントは「支払いインテント」ではありません。 価格設定の インテント は、加盟店登録時に使用する再利用可能な 手数料テンプレート であり、金銭の受け取り、承認、またはキャプチャは行いません。他の一部のゲートウェイ（Stripe など）では、取引／承認オブジェクトを「支払いインテント」と呼びますが、Payroc にそのようなエンドポイントはありません（支払いは別のトランザクション API で扱われます）。開発者が「支払いインテント」と言った場合、または手数料の定義ではなく カードへの請求や支払いの受け取り を希望しているように見える場合は、何を意味しているのかを確認してから作業を始めてください。資金を移動したい場合は、このスキルではなく、支払い／トランザクション API を案内してください。

価格設定インテントは任意です。 create-merchant-platform は、pricing.type: "intent"（pricingIntentId による参照）または pricing.type: "agreement"（手数料オブジェクト全体をインラインで指定）を受け付けます。同じ手数料体系で多くの加盟店を登録する場合は価格設定インテントを使用し、単発の契約では使用しないでください。

すべての列挙値、プランごとの fees の形式、完全な記入例など、フィールドの詳細については references/api-schema.md を読んでください。列挙値、ネストされたフィールドの詳細、または単位を確認する場合は、必ず読み込んでください。列挙値とフィールド名は、記憶ではなく、このリファレンスに記載されたものを使用してください。

---

この仕組み

このスキルは、入力フォームではなく、聞き取り形式です。開発者は、業務上の言葉で価格設定を説明します。たとえば、「インターチェンジプラス、Mastercard／Visa／Discover では0.25% + 10¢、年間手数料99ドル、ゲートウェイは月額25ドル」 のように説明します。その内容を、正しいネスト構造を持つポリモーフィックな JSON 本文に変換してください。開発者に完全な JSON 構造を渡すよう求めたり、空のテンプレートを提示したりしないでください。会話を通じて値を集め（Step 2 では planType から始めます）、その後リクエストを組み立てます。

開発者が完全または部分的な JSON 本文を貼り付けた場合は、そのまま受け取り、不足部分を補ってください。references/api-schema.md に照らして検証し、不足している情報だけを尋ねてください。

---

クイックリファレンス

Base URL (test):  https://api.uat.payroc.com/v1
Base URL (prod):  https://api.payroc.com/v1

GET    /pricing-intents                     # list (paginated)
POST   /pricing-intents                     # create            (Idempotency-Key required)
GET    /pricing-intents/{pricingIntentId}   # retrieve
PUT    /pricing-intents/{pricingIntentId}   # full replace      -> 204 No Content
PATCH  /pricing-intents/{pricingIntentId}   # JSON Patch (RFC 6902, Idempotency-Key required)
DELETE /pricing-intents/{pricingIntentId}   # delete            -> 204 No Content

Authorization:   Bearer <token>     (all operations)
Idempotency-Key: <uuid-v4>          (POST and PATCH only)
Content-Type:    application/json    (POST, PUT, PATCH)

---

Step 1 — ベアラートークンを取得する

認証コードを出力する前に references/identity-call.md を読んでください。エンドポイント URL、ヘッダー名、またはレスポンスの形式を推測せず、リファレンスに記載された内容のみを使用してください。

トークンの有効期限は約1時間です。セッションごとに API キーを交換するか、期限切れ前に更新してください。

# Test / sandbox
curl -X POST https://identity.uat.payroc.com/authorize \
  -H "x-api-key: YOUR_API_KEY"

# Production
curl -X POST https://identity.payroc.com/authorize \
  -H "x-api-key: YOUR_API_KEY"

レスポンス：

{
  "access_token": "eyJhbGc....",
  "expires_in": 3600,
  "token_type": "Bearer"
}

以降のすべてのリクエストで Authorization: Bearer <access_token> を使用してください。

---

ステップ 2 — 料金プログラムを選択する

最も重要な判断は processor.card.planType です。これは fees オブジェクトの構造を決定します。次のいずれかを選択してください。

planType	料金モデル	使用する場面
interchangePlus	インターチェンジフィーの実費＋固定マークアップ	透明性の高いコストプラス方式。最も一般的
interchangePlusPlus	インターチェンジフィー＋マークアップを、適格／中間／非適格に分けて設定	レート区分を設けたコストプラス方式
tiered3	3段階：適格／中間適格／非適格	シンプルな段階別料金
tiered4	3段階＋プレミアム	プレミアムカード区分を含む段階別料金
tiered6	プレミアム＋規制対象／規制対象外のデビットカード区分	詳細な段階別料金
flatRate	一律の料率＋取引ごとの手数料	シンプルで予測しやすい料金
consumerChoice	月額サブスクリプション＋現金以外の支払いへのサーチャージ／現金割引	サーチャージ／現金割引プログラム
rewardPayChoice	サブスクリプション＋デビットとクレジットを個別に処理	リワードカードの差別化

リクエスト本文を作成する前に、該当する references/api-schema.md のサブセクションを読み、そのバリエーションで必要となる fees フィールドを確認してください。planType の識別子の値は、必ずリファレンスに記載されたものを使用してください。

---

ステップ 3 — リクエスト本文を作成する

トップレベルのキーのうち、key、country、version、base の 4 つは必須です。processor、gateway、services、metadata は省略可能ですが、ほとんどの場合 processor と gateway を含めます。

{
  "key": "RETAIL-STANDARD-2026",
  "country": "US",
  "version": "5.2",
  "base": { ... },
  "processor": { "card": { "planType": "...", "fees": { ... } }, "ach": { ... } },
  "gateway": { "fees": { ... } },
  "services": [ ... ],
  "metadata": {}
}

主なルール：

• key はテンプレート用の独自識別子（自社の記録用）で、Payroc が割り当てる id とは異なります。必須です。
• country には US のみ指定できます。version には 5.2 のみ指定できます。
• すべての金額はセント単位です — transaction: 10 は $0.10、monthly: 2500 は $25.00 です。
• パーセンテージ（volume、割引率）は小数点以下 2 桁までの数値です。0.25 は 0.25% を意味します。
• base には、addressVerification、annualFee（独自に必須の amount を持つオブジェクト）、regulatoryAssistanceProgram、merchantAdvantage、maintenance、minimum、batch の 7 つすべてが必要です。すべてのキーに数値を指定する必要があり、そうしないと 400 エラーになります。OpenAPI 仕様では addressVerification、regulatoryAssistanceProgram、merchantAdvantage を null 許容としていますが、稼働中の UAT API ではこの 3 つすべてに null を指定すると拒否されます（"must not be empty"、2026-06-19 に確認済み）。そのため数値を送信し、加盟店に請求しない項目には 0 を使用してください。キー自体も省略しないでください。必須キーを省略した場合も検証に失敗します。任意の手数料（pciNonCompliance、chargeback など）にはサーバー側のデフォルト値があります。リファレンスを参照してください。
• processor.card.fees の構造は planType によって異なります（ステップ 2 とリファレンスを参照）。interchangePlus では fees.mastercardVisaDiscover が必須です。
• gateway.fees には monthly、setup、perTransaction、perDeviceMonthly が必要です。
• ACH のみのテンプレート： 加盟店が ACH のみを処理する場合、processor.card は省略可能です。card 全体を省略し、processor.ach のみを送信してください（その fees オブジェクトには独自の必須キーがあります。リファレンスを参照してください）。gateway も省略可能です。ゲートウェイがない場合は、ゲートウェイ手数料をすべてゼロにして送信するのではなく、オブジェクト全体を省略してください。ACH のみのテンプレートでも base は必須です。

interchangePlus の最小構成例：

{
  "key": "RETAIL-STANDARD-2026",
  "country": "US",
  "version": "5.2",
  "base": {
    "addressVerification": 10,
    "annualFee": { "amount": 9900, "billInMonth": "december" },
    "regulatoryAssistanceProgram": 0,
    "merchantAdvantage": 0,
    "maintenance": 995,
    "minimum": 2500,
    "batch": 25
  },
  "processor": {
    "card": {
      "planType": "interchangePlus",
      "fees": {
        "mastercardVisaDiscover": { "volume": 0.25, "transaction": 10 },
        "amex": { "type": "optBlue", "volume": 0.30, "transaction": 10 }
      }
    }
  },
  "gateway": {
    "fees": { "monthly": 2500, "setup": 0, "perTransaction": 10, "perDeviceMonthly": 0 }
  }
}

flatRate の最小構成例 — カードの fees には standardCards を使用します（mastercardVisaDiscover はありません）。この場合、amex でサポートされるのは direct バリエーションのみです。また、仕様上 null 許容の base フィールドには 0 を指定しています（UAT は null を拒否します）。

{
  "key": "SOFTWARE-SUBS-FLATRATE-2026",
  "country": "US",
  "version": "5.2",
  "base": {
    "addressVerification": 0,
    "annualFee": { "amount": 0, "billInMonth": "december" },
    "regulatoryAssistanceProgram": 0,
    "merchantAdvantage": 0,
    "maintenance": 0,
    "minimum": 0,
    "batch": 0
  },
  "processor": {
    "card": {
      "planType": "flatRate",
      "fees": {
        "standardCards": { "volume": 2.90, "transaction": 30 }
      }
    }
  },
  "gateway": {
    "fees": { "monthly": 0, "setup": 0, "perTransaction": 0, "perDeviceMonthly": 0 }
  }
}

ほかの planType を使用する場合は、推測せずに references/api-schema.md の該当サブセクションを読み、正確な fees の構造を確認してください。フラットな mastercardVisaDiscover を使うのは interchangePlus のみです。段階別プランでは qualRates 形式のオブジェクトを使用し、サブスクリプションプラン（consumerChoice、rewardPayChoice）では monthlySubscription 形式を使用します。

推奨される初期値

仕様では、一部の base 手数料にデフォルト値が定義されています。開発者が指定しない場合は、これらを初期値として使用してください（すべてセント単位です）。

フィールド	デフォルト
base.pciNonCompliance	7495（月額）
base.voiceAuthorization	95
base.chargeback	2500
base.retrieval	1500
base.earlyTermination	57500
base.annualFee.billInMonth	december
base.platinumSecurity.amount	1295 月額／15540 年額
rewardPayChoice credit cardChargePercentage	3
rewardPayChoice credit merchantChargePercentage	0.9

交渉可能な料率には、API で強制される範囲も、文書化された「一般的な」値もありません。 マークアップの volume 割合と transaction ごとの手数料は、加盟店ごとに商業交渉で決定されます。妥当そうな範囲を作り上げたり、「通常の」料率を提案したりせず、合意済みの値を開発者に確認してください。（これらのデフォルト値が仕様で示されている唯一の値の指針です。references/api-schema.md を参照してください。）

---

Step 4 — 料金設定インテントの作成（POST）

Idempotency-Key には、必ず新しい UUID v4 を生成してください。同じ送信を再試行する場合は、同じキーを再利用してください。API は重複を作成せず、元のレスポンスを返します。新たに送信する場合は、新しい UUID を生成してください。

curl -X POST https://api.payroc.com/v1/pricing-intents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d @pricing-intent.json

201 Created — インテントが作成され、承認待ちになります。

{
  "id": "PI-XXXX",
  "key": "RETAIL-STANDARD-2026",
  "status": "pendingReview",
  "createdDate": "2026-06-16T12:00:00Z",
  "base": { ... },
  "processor": { ... }
}

id は直ちに保存してください。Payroc が審査するまでは status は pendingReview で、承認されると active、却下されると rejected になります。インテントを加盟店に割り当てられるのは、active になってからです。

ID は不透明です。 これらの例で使用している PI-XXXX 形式は、読みやすさのためのものにすぎません。id は形式が保証されず、環境によって異なる不透明な文字列として扱ってください。UAT ではプレーンな整数（例：5722）として返されます。PREFIX-XXXX パターンに照らして検証したり、解析したりしないでください。

組み立てたリクエスト本文を開発者に提示してください。 作成に成功したら、作成した最終的なリクエスト JSON を開発者に渡してください（またはファイルに書き込んでください）。監査用に保管しておく価値があり、後から変更する際の出発点にもなります。後続の変更では、全体を PUT で再送信するか、コピーを調整して PATCH で送信してください（Step 6 を参照）。

---

Step 5 — 取得と一覧表示（GET）

ID を指定して 1 件取得します。

curl https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN"

一覧を取得します（ページネーションあり。limit と before／after カーソルを指定できます。これらのカーソルは同時に使用できません）。

curl "https://api.payroc.com/v1/pricing-intents?limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

一覧レスポンスでは、結果が { limit, count, hasMore, links, data: [ ... ] } に格納されています。次のページに進むには、links または after カーソルを使用してください。id がわからない場合は、一覧からインテントを探してください。

---

Step 6 — 更新（PUT と PATCH）

料金設定インテントを更新しても、すでにオンボーディング済みの加盟店には変更が反映されません。更新によってインテント自体が再承認のために pendingReview に戻るかどうかは、ドキュメントに記載されていません。回答で再審査される（またはされない）と決めつけないでください。更新後のステータスがワークフローに関わる場合は、推測するのではなく、インテントを再度 GET して status を確認してください。

PUT — 全置換。 作成時と同じ形式の pricingIntent 本文をすべて送信します。204 No Content が返されます。冪等性キーは不要です。

curl -X PUT https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @full-pricing-intent.json

PATCH — RFC 6902 JSON Patch による部分更新。 本文は部分オブジェクトではなく、操作の配列です。Idempotency-Key が必要です。更新後のインテントを含む 200 が返されます。

curl -X PATCH https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '[ { "op": "replace", "path": "/gateway/fees/monthly", "value": 1995 } ]'

安全な単一フィールドのパッチ。 RFC 6902 では、現在の値を検証する test 操作を先頭に追加できます。検証に失敗するとパッチ全体が拒否されるため、想定と異なる値を上書きすることはありません（同時編集への対策として便利です）。手数料を 1 つ変更する場合は、この方法を推奨します。

[
  { "op": "test",    "path": "/gateway/fees/monthly", "value": 2500 },
  { "op": "replace", "path": "/gateway/fees/monthly", "value": 1995 }
]

特定の項目（単一の手数料など）を変更する場合は PATCH を使用し、テンプレート全体を置き換える場合は PUT を使用してください。手数料、カスタムの key／名前、services 配列を更新できます。

---

ステップ 7 — 削除（DELETE）

curl -X DELETE https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN"

204 No Content が返されます。削除は取り消せません。削除後にインテントを復元したり、今後の加盟店登録申請に割り当てたりすることはできません。

---

ステップ 8 — エラーの処理

エラーは、エンベロープとして RFC 7807 の問題詳細形式を使用します。最上位の type、title、status、detail、instance は、RFC 標準のメンバーです。Payroc はエンベロープを独自に拡張し、errors 配列を追加しています。この配列とその内容は Payroc 独自のものであり、RFC 7807 では定義されていません。各 errors[] アイテムには parameter、detail、message が含まれます。parameter はエラーが発生したフィールドの JSON パス（例：country、base.annualFee.amount）です。detail は短い理由（"Invalid format"、"Required field not populated"）で、最上位の RFC detail とは異なります。message は人が読める説明です。parameter を使って、各エラーをリクエストボディ内の該当フィールドに直接対応付けてください。（エンベロープの形式と正規のエラー type カタログについては、references/error-response-format.md を参照してください。）

公開されている OpenAPI 仕様では各アイテムの message のみが記載されていますが、実際の API では parameter と detail も返されます（2026-06-16 に UAT で確認）。修正箇所を最もすばやく見つけるには、parameter を確認してください。

ステータス	シナリオ	対応
400	検証エラー	各 errors[].parameter でフィールドを特定し、message／detail で理由を確認します。ボディを修正し、新しい冪等性キーで再送信してください（修正後のボディは異なるため、古いキーを再利用すると 409 になるおそれがあります。下記の注記を参照してください）
401	トークンの期限切れまたは無効	再認証し、新しいベアラートークンを取得してください
403	権限不足	API キーのスコープを確認してください。instance／resource に試行した操作が示されます
404	価格設定インテントが見つからない	pricingIntentId を確認してください。リストを使って該当するものを探してください
406	許容できない形式	Content-Type／Accept ヘッダーとボディの形式を確認してください
409	競合 — 冪等性キーが変更されたボディとともに再利用された	反射的に新しいキーで再度 POST しないでください。下記の注記を参照してください。すでにインテントを作成している可能性があります
500	サーバーエラー	指数バックオフで再試行し、errors があれば通知してください

作成時の 409 には注意が必要です。すでにインテントを作成している可能性があります。 409 は、異なるボディとともに Idempotency-Key が再利用されたことを意味します（典型例：誤字を修正し、元のキーで再送信した場合）。再送信する前に、最初の POST が実際に成功したかを確認してください。成功したかどうかで修正方法が異なります。

• 成功していた場合（201／id を受け取った、または GET /pricing-intents にインテントが表示される）→ インテントは古い値で既に存在しています。PATCH（または PUT）で既存のインテントを修正してください。再度 POST すると、重複した pendingReview インテントが残ってしまうため、再度 POST しないでください。
• 何も作成されていない場合（id が一度も返されていない）→ 新しい UUID Idempotency-Key と修正後のボディで再度 POST してください。

同じキーを再利用できるのは、バイト単位で完全に同一のリクエストを再試行する場合のみです。ボディに変更があれば、新しいキーが必要です。（存在するインテントが不明な場合は、GET /pricing-intents で確認してください。）

---

create-merchant-platform での ID の使用

価格設定インテントが active になったら、加盟店登録時に処理アカウントの pricing フィールドへ割り当てます。

"pricing": {
  "type": "intent",
  "pricingIntentId": "PI-XXXX"
}

これは merchant-platform の pricing オブジェクトにおける intent バリアントです。もう一方はインラインの agreement バリアントです。create-merchant-platform を参照してください。

---

よくある落とし穴

• PATCH は部分オブジェクトではなく JSON Patch です：{ "gateway": { ... } } ではなく、[{ "op": "...", "path": "...", "value": ... }] を送信してください
• PUT は本文なしで 204 を返します：更新後のレコードが返されることを期待しないでください。必要な場合は、もう一度 GET してください
• base の手数料には null ではなく数値が必要です：addressVerification、regulatoryAssistanceProgram、merchantAdvantage は必須キーです。仕様上は null 許容ですが、UAT では null が拒否され（「空であってはなりません」）、数値（請求しない場合は 0）を送信する必要があります。また、キーを省略してはいけません
• 400 を修正する場合も、完全な本文を作成してください：修正したペイロードにも、必須の base キーすべてと 4 つの gateway.fees キーすべてを含めてください。含めないと、新たに 400 が発生します
• 金額の単位はセントです：すべての手数料はセント単位の整数です。パーセンテージは数値（小数点以下 2 桁まで）です
• key は必須で、値は自分で決めます：Payroc の id とは別の、独自のテンプレート識別子です
• 冪等性キーを指定するのは POST と PATCH のみです：PUT、GET、DELETE では指定しません
• fees の形式は planType によって異なります：入力する前に、該当するリファレンスのサブセクションを確認してください
• US / 5.2 のみです：現時点では、country と version が受け付ける値はそれぞれ 1 つだけです

---

フィールドの完全なリファレンス

以下については references/api-schema.md を参照してください。

• すべての列挙値（planType、status、amex.type、billInMonth、billingFrequency など）
• planType ごとの fees スキーマ（インターチェンジプラス、段階制の 3／4／6 段階、定額制、コンシューマー／リワードの選択制）
• 単位を含む base、gateway、ach、services オブジェクトのスキーマ
• 注釈付きの作成リクエストおよび PATCH の例と、エラースキーマ