create-merchant-platform

マーチャントプラットフォームの作成

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

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

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

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

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

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

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

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

---

POST https://api.payroc.com/v1/merchant-platforms は、新しいマーチャントのオンボーディングプロセスを開始します。Payroc が申請を審査し、merchantPlatformId と processingAccountId を割り当てます。端末の注文と、その後のすべてのオンボーディング処理で必要になるため、両方を保存してください。

フィールドの完全なリファレンスと注釈付きのリクエスト例については、references/api-schema.md を読んでください（列挙値、ネストされたフィールドの詳細、または完全な実例が必要なときに読み込みます）。

---

クイックリファレンス

POST  https://api.payroc.com/v1/merchant-platforms
Authorization:   Bearer <token>
Idempotency-Key: <uuid-v4>
Content-Type:    application/json

---

ステップ 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 — リクエストボディを作成する

ボディには、必須のトップレベルキーが 2 つあります。

{
  "business": { ... },
  "processingAccounts": [ { ... } ],
  "metadata": {}
}

metadata は任意です。Payroc がレスポンスで返す独自のキーと値のペア（たとえば、社内の顧客 ID）を付加するために使用してください。

事業者オブジェクト

法人を記述します。必須フィールドは次のとおりです。

フィールド	型	備考
name	string	法人の正式名称
taxId	string	EIN（米国）
organizationType	enum	値についてはスキーマリファレンスを参照してください
countryOfOperation	string	"US"
addresses	array	"type": "legalAddress" のエントリを 1 つ含める必要があります
contactMethods	array	"type": "email" のエントリを 1 つ以上含める必要があります

加盟店アカウントの処理

各要素で1つのMIDを登録します。配列には少なくとも1つのエントリが必要です。 アカウントごとに必要な主なフィールド：

フィールド	備考
doingBusinessAs	商号／DBA名
merchandiseOrServiceSold	平易な英語による説明
businessStartDate	YYYY-MM-DD
timezone	例："America/New_York" — 全リストはスキーマリファレンスを参照してください
address	事業所の所在地
contactMethods	メールアドレスが必須です
owners	以下の所有者ルールを参照してください
processing	取引量とカード決済の受け入れ
funding	銀行口座と精算スケジュール
pricing	料金設定インテントIDまたは料金契約全体
signature	加盟店による契約の署名方法
addendums	配列 — 特別なフォームが適用されない場合は []。以下の追加書類を参照してください

businessType（retail、restaurant、internet、moto、lodging、notForProfit）と categoryCode（4桁のMCC整数）は任意ですが、判明している場合は送信してください。後続の 加盟店登録審査でもこれらが使用されます。processor（tsys | fiserv、デフォルトは tsys）も 任意ですが、デフォルトに頼らず明示的に送信してください。

追加書類 — 加盟店に、契約書と一緒に次のいずれかのフォームを送付する必要があるか確認してください： 分割払い、資金移動サービス、遠隔医療、銃器、薬局のCNPコンプライアンス、CBD、 タバコのCNP、寄付、Clover機器、またはRoc Giving。リクエストでは addendums が必須ですが、 該当するものがない場合は [] が有効な回答です。種類ごとのペイロード形式については references/api-schema.md#addendums を参照してください（CloverとRoc Givingには実際のフィールドがあり、 その他は証明のみです）。

所有者ルール — 各加盟店アカウントには次の要件があります：

• relationship.isControlProng: true を持つ所有者がちょうど1人（支配権を持つ所有者は1人のみ）
• relationship.isAuthorizedSignatory: true を持つ所有者が少なくとも1人

1人の所有者が両方を兼ねることはできません — APIは両方のフラグが設定された所有者を拒否します（「どちらか一方、またはどちらでもない必要があります」）。そのため、少なくとも2人の所有者（支配権を持つ所有者1人と、それとは別の署名権限を持つ所有者1人）が必要です。各所有者にはさらに、firstName、lastName、dateOfBirth （YYYY-MM-DD）、address、identifiers（国民ID／SSN）、および contactMethods のメールアドレスが必要です。

料金設定の簡略化 — 料金テンプレートがある場合は、次を使用します：

{ "type": "intent", "pricingIntentId": "<id>" }

それ以外の場合は、agreement オブジェクト全体を指定してください（構造についてはスキーマリファレンスを参照してください）。

署名 — 次の方法で、メールで署名リンクを送信します：

{ "type": "requestedViaEmail" }

または、リダイレクトを管理している場合は、HATEOASリンクオブジェクトとともに "requestedViaDirectLink" を使用します。

取引量の内訳 — processing.volumeBreakdown.cardPresent + mailOrTelephone + ecommerce の合計は、正確に100でなければなりません。

金額の単位はセントです — transactionAmounts.average: 5000 は50.00ドルを意味します。

---

ステップ3 — リクエストを送信する

Idempotency-Key には、必ず新しいUUID v4を生成してください。このキーはリクエスト本文に紐付けられるため、 バイト単位で完全に同一の送信を再試行する場合に限り、同じキーを再利用してください — その場合、APIは 重複を作成せず、元のレスポンスを返します。まったく新しい送信の場合、または 400 の修正後に再送信する場合 （修正後の本文は古いキーに一致しなくなります）は、新しいUUIDを生成してください — 本文を変更して古いキーを再利用すると、 409 が返されます。

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

---

ステップ4 — レスポンスを処理する

201 Created — 加盟店登録リクエストが受理されました：

{
  "merchantPlatformId": "MP-XXXX",
  "processingAccounts": [
    {
      "processingAccountId": "PA-XXXX",
      "status": "entered"   // may also be "pending" depending on timing
    }
  ],
  "links": [ ... ]
}

merchantPlatformId と各 processingAccountId は、ただちに永続化してください。初期の status は通常 "entered"（受信済み、審査前）ですが、処理のタイミングによっては "pending" として届く場合もあります — ステータスの変更を検出するには、作成レスポンスの値に依存せず、ポーリングするかWebhookを使用してください。

IDは不透明です。 これらの例にある MP-XXXX / PA-XXXX / PI-XXXX という形式は、 読みやすさのためだけのものです。すべてのIDは、形式が保証されず環境によって異なる不透明な文字列として扱ってください — UATでは通常の整数（例：9815）として返されます。PREFIX-XXXX のパターンに照らして検証または解析しないでください。

ステップ 5 — エラーに対処する

エラーは RFC 7807 に準拠しており、Payroc のドキュメントにリンクする type URL に加え、検証エラーの場合は errors 配列が含まれます。

ステータス	シナリオ	対処方法
400 validation	フィールドの問題	errors[].parameter の各フィールドを修正し、新しい冪等性キーを使って再送信します（修正した本文には新しいキーが必要です）
400 idempotencyKeyMissing	ヘッダーが不足	リクエストに Idempotency-Key: <uuid-v4> を追加します
400 addendum/processor validation	認識されない、または重複した addendums[].type、必須フィールドが不足している addendum、または認識されない processor	致命的または予期しないエラーではありません。references/api-schema.md の addendum/processor エラーテーブルを参照し、指摘されたフィールドを修正して再送信します
401	トークンの期限切れまたは無効	再認証して、新しいベアラートークンを取得します
403	権限が不足	API キーのスコープを確認し、Payroc のサポートに連絡します
409 resourceAlreadyExists	加盟店の重複	加盟店の登録がすでに完了しているか確認し、既存のレコードを取得します
409 idempotencyKeyInUse	異なるペイロードでキーを再利用	新しい送信には新しい UUID を生成します
409 taxIdInUse	その Tax ID を持つ加盟店が存在	代わりに既存の加盟店プラットフォームを取得します
500	サーバーエラー	指数バックオフで再試行し、存在する場合は errors 配列を提示します

検証エラーの読み方 — レスポンスには RFC 7807 の問題詳細エンベロープ（type、 title、status、detail、instance）が使われます。Payroc は RFC 7807 で定義されていない errors 配列を拡張して追加しています。各 errors[] 項目には、parameter（エラーが発生したフィールドの JSON パス）、detail（短い理由。トップレベルの detail とは異なります）、message（人間が読める説明）が含まれます。エンベロープの形式と正規のエラー type カタログについては、references/error-response-format.md を参照してください。UAT からの実際の 400（空の本文）：

{
  "type": "https://docs.payroc.com/api/errors#bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "One or more validation errors occurred, see error section for more info",
  "instance": "https://api.uat.payroc.com/v1/merchant-platforms",
  "errors": [
    {
      "parameter": "merchantPlatform.business",
      "detail": "Invalid value",
      "message": "'business' must not be empty."
    },
    {
      "parameter": "merchantPlatform.processingAccounts",
      "detail": "Required field not populated",
      "message": "'processingAccounts' must not be empty."
    }
  ]
}

各 parameter パスは、リクエスト本文内のエラーが発生したフィールドに対応します。これを使って問題の箇所を特定し、修正してください。指摘されたすべてのフィールドを、修正した単一のペイロード内で修正して再送信します。（公開されている OpenAPI 仕様では各項目に message のみが記載されていますが、実際の API は parameter と detail も返します。2026-06-16 に UAT で確認済みです。）

---

よくある落とし穴

• 支配権を持つオーナー／正式な署名権限者がいない：すべての決済処理アカウントの owners 配列に両方の役割が必要です。ただし、1 人のオーナーが両方を兼ねることはできません（API に拒否されます）。そのため、少なくとも 2 人のオーナー（支配権を持つオーナー 1 人と、それとは別の正式な署名権限者 1 人）を指定します
• 数字以外を含む電話／FAX の value：phone／mobile／fax の value には数字のみを指定する必要があります。+、空白、句読点は使用できません（例：+1 512 555 0199 ではなく 5125550199）
• 取引量の内訳の合計が 100 にならない：cardPresent + mailOrTelephone + ecommerce は正確に 100 である必要があります。ecommerce > 0 の場合、アカウントの website が必要です
• 金額はセント単位：すべての金額（transactionAmounts、monthlyAmounts、acceleratedFundingFee）はセント単位の整数です
• 日付の形式：dateOfBirth と businessStartDate は YYYY-MM-DD 形式である必要があります
• 冪等性キーがない：すべての POST リクエストで Idempotency-Key が必須です。指定しない場合は 400 が返されます
• 異なるペイロードでキーを再利用：一意の送信ごとに、それぞれ独自の UUID が必要です

---

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

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

• すべての列挙値（organizationType、businessType、timezone、fundingSchedule など）
• 完全なネストされたオブジェクトスキーマ（owners、processing、funding、pricing、signature）
• 注釈付きのエンドツーエンドのリクエスト本文の例