integrate-payroc-cloud

Payroc Cloud を統合する

対象範囲：Payroc Cloud 経由の対面カード決済 — セミインテグレーション製品の API 部分 です。 実際の決済端末を動かすクラウドの 指示 の送信、ポーリング、取得を行います： 売上、事前承認、返金（参照あり・なし）、取消、署名の取得、クローズドループ読み取り、および読み取り専用の端末検索です。実際の端末の設定／ペアリングは対象外です。このスキルは、端末の serialNumber を取得した後から開始します。

バージョンを確認する（最初に実行）

何かを案内したり、フローを開始したりする前に、このスキルが最新であることを確認します。

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

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

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

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

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

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

---

Payroc Cloud の仕組み

セミインテグレーションモデルでは、POS は決済端末と直接通信することはありません。POS は HTTPS 経由で Payroc ゲートウェイに 指示 を送信し、ゲートウェイが端末に中継します。端末がカードの処理（タップ／挿入／PIN／署名）を実行し、結果はゲートウェイを経由して返され、POS が取得します。

  POS / POS app  --HTTPS-->  Payroc gateway  -->  payment device (Payroc App)
       ^                          |                        |
       +-------- poll status <----+<--- result ------------+

すべての通信がゲートウェイを経由するため、統合は純粋な REST で行われます。組み込む端末 SDK は不要で、サーバー上にカードデータを保持する必要もありません。このスキルでは、その REST インターフェースを扱います。

対象範囲と対象外：

• 対象（純粋な API）： 指示（決済／返金／署名）の作成と送信、ポーリング、決済／返金／署名結果の取得、処理中の指示のキャンセル、クローズドループのペイロードの読み取り、参照あり／なしの返金と取消、GET /devices による serialNumber の検索。
• 対象外（ハードウェア）： 実際の端末の設定やペアリング（Android／Ingenico／ID TECH のセットアップ）、タップ／挿入／スワイプ／PIN／画面上での署名操作、実際のシリアル番号とターミナルの紐付け。開発者がこれらを必要としている場合は、API 作業ではなく端末のセットアップであることを明確に伝えてください。

このスキルでは、端末と serialNumber は既知の入力値として扱います。まだ取得していない場合は、GET /devices で検索できます（読み取り専用で、ハードウェアは不要です）。また、Payroc Cloud Simulator（cloud.uat.payroc.com）では、ハードウェアなしでテストできるよう、ブラウザーのタブごとにモックのシリアル番号が発行されます。

---

参考資料 — これらを読み、記憶から出力しないでください

このスキルは、以下のローカルな references/ ファイルから出力します。ライブ検索や記憶には頼りません。 参照資料には、それぞれ異なる種類の質問に答える、相互に補完する2種類があります。誤った資料を使うことは、よくある失敗の原因です。

• references/api-schema.md — 通信で送受信される内容。 フィールド名、型、必須フラグ、列挙値、リクエスト／レスポンスの形式、エンドポイント一覧、エラーエンベロープが記載されています。フィールド名や指定可能な値を確認するときは、必ずこちらを読んでください。列挙値とフィールド名はすべて、記憶ではなくこちらから出力してください。 もっともらしく見える値（例：列挙値にないステータス "approved" や entryMethod の "chip"）を使うことが、よくある失敗の原因です。
• references/narrative-run-a-sale.md および references/narrative-extend.md — 呼び出しの順序。 どの呼び出しを最初に行うか、ポーリングしてリンクをたどるフローの組み立て方、署名、参照付き／参照なしの返金、取消などの後続フローがコアパターンをどう拡張するかが記載されています。
• references/error-response-format.md — エラーエンベロープ（RFC 7807）＋ Payroc の errors[] ＋標準エラータイプのカタログ。 サーバー側 API 呼び出しのエンベロープ形式と標準エラー type のカタログが記載されています。ステータスごとの表は api-schema.md にあります。

ソース URL と最終同期日は references/_sources.md に記載されています。

正直な制約事項。 これらの参考資料は、Payroc の公開ドキュメントをもとにまとめたもので、Cloud 対応アカウントや検証用ハードウェアを使った検証は行っていません。契約（パス、フィールド、列挙値、指示のライフサイクル）はドキュメントに直接基づいており、信頼できます。一方、Cloud のエラーレスポンス形式は共通スキル標準に準拠すると想定していますが、Cloud での確認はできていません。厳密なエラー処理ロジックを実装する開発者には、この点を伝えてください。

---

基本原則

1. 質問する前に調査する。 まず開発者のコードベースを確認します。使用言語、HTTP クライアント、設定とシークレットの扱い、既存の Payroc または POS 連携などを把握し、推測できることを尋ねるのではなく、相手の状況に合わせて質問します。
2. 値ごとに確認してから出力する。 列挙値やフィールド名（currency、entryMethod、指示の status、mitAgreement、tip.type、返金の responseCode、決済検索の type など）を出力する前に、references/api-schema.md で確認してください。スキル内の例は形式を把握するためのものです。各リクエスト本文を組み立てる際に参考資料を読む代わりにはなりません。
3. 一度覚える基本パターン。 売上、返金、署名はすべて同じ非同期指示です。送信（202）→ ポーリング → リンクをたどる → 取得。まずこの流れを身につければ、あとは応用です。
4. 指示 ID とリソース ID は異なります。 ポーリングで返されるのは paymentInstructionId です。完了した指示の link.href が指すのは、別の ID である paymentId です。必ずリンクをたどってください。指示 ID からリソース URL を組み立ててはいけません。
5. 202 ≠ 承認済み。 202 は、ゲートウェイが指示を受け付け、デバイスに中継したことを意味します。売上の実際の結果（銀行による承認／拒否）は指示ではなく、取得した決済に記録されています。
6. 認証情報をハードコードしない。 API キーや端末／シリアル値は、環境変数またはシークレットマネージャーから取得します。ソースコードには記述しません。

---

クイックリファレンス

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

# Instruction submit (runs on the device) — Idempotency-Key required
POST   /devices/{serialNumber}/payment-instructions      -> 202
POST   /devices/{serialNumber}/refund-instructions       -> 202   (unreferenced refund)
POST   /devices/{serialNumber}/signature-instructions    -> 202

# Poll an instruction (gateway long-holds ~60s) / cancel it
GET    /payment-instructions/{id}                         -> 200
DELETE /payment-instructions/{id}                         -> 204   (only while inProgress, else 409)
#   ...same GET/DELETE shape for refund-instructions and signature-instructions

# Retrieve the resulting resource (follow link.href from the completed instruction)
GET    /payments/{paymentId}        GET /refunds/{refundId}        GET /signatures/{signatureId}
GET    /closed-loop-reads/{closedLoopReadId}

# Referenced refund & reversal (standard payments API, NOT device instructions) — Idempotency-Key required
POST   /payments/{paymentId}/refunds                      -> 201
POST   /payments/{paymentId}/reverse                      -> 200
GET    /payments        GET /payments/{paymentId}         # find / retrieve a payment
GET    /devices                                           # find a serialNumber

Headers: Authorization: Bearer <token>   Content-Type: application/json   Idempotency-Key: <uuid-v4>

---

ステップ 1 — ベアラートークンを取得する

認証コードを出力する前に references/identity-call.md を読んでください。エンドポイント URL、ヘッダー名、レスポンス形式を推測せず、参考資料に記載されたものだけを使用してください。

トークンの有効期限は約1時間です（expires_in: 3600）。各セッションの開始前に API キーを交換し、有効期限が切れる前に余裕をもって更新してください。

# Test / sandbox (production: identity.payroc.com)
curl -X POST https://identity.uat.payroc.com/authorize \
  -H "x-api-key: $PAYROC_API_KEY"

レスポンスには access_token、expires_in、token_type: "Bearer" が含まれます。それ以降のすべてのリクエストで Authorization: Bearer <access_token> を送信してください。

---

ステップ 2 — 指示のパターン（送信 → ポーリング → リンクをたどる → 取得）

references/narrative-run-a-sale.md を読みます。これが Payroc Cloud の中核であり、すべての操作で使用します。

1. 送信 — 新しい Idempotency-Key を付けて、デバイスに指示を送信します。202 Accepted と { status: "inProgress", <x>InstructionId, link } が返されます。指示 ID を保存します。
2. ポーリング — GET /<x>-instructions/{id} を実行します。ゲートウェイはステータスが変わるのを待つ間、応答を最大約 60 秒間保留します。 そのため、短い間隔でループしたり、独自にスリープを挟んだりしないでください。GET を実行し、 応答が返るのを待ち、まだ inProgress の場合にのみ再実行します。ステータスは inProgress、 completed、failure、canceled です。記憶に頼らず、references/api-schema.md で確認してください。
3. completed の場合 — 応答の link.href は実際のリソースを指しています。リンクをたどります。 GET /payments/{paymentId}（または /refunds/{id}、/signatures/{id}）を実行します。この URL を 指示 ID から組み立てないでください。ID はそれぞれ異なります。取得した支払いには transactionResult に銀行の結果が含まれます。complete のような単一の値を覚えて判断するのではなく、 references/api-schema.md で承認を示す値の全一覧を確認し、transactionResult.status に基づいて分岐してください （たとえば ready は、承認済みでキャプチャ待ちの状態を示す承認です）。
4. failure の場合 — errorMessage を確認します。canceled の場合 — 指示は先にキャンセルされています。

キャンセル。 DELETE /<x>-instructions/{id} は 204 を返しますが、指示が inProgress の間に限られます。 完了、失敗、キャンセルのいずれかになった後は、DELETE は 409 Conflict を返します。現在の状態が不明な場合は、 キャンセルする前に指示を GET して status を確認してください。

チェックポイント

送信すると指示 ID と self リンクを伴う 202 が返され、ポーリングを続けると最終的に completed （または errorMessage を伴う failure）になります。完了リンクをたどるとリソースを取得できます。

---

ステップ 3 — 売上指示を作成する

本文を作成する際は references/api-schema.md の paymentInstructionRequest セクションを読みます。 必須項目は processingTerminalId と order（orderId、amount、currency）です。

POST /v1/devices/{serialNumber}/payment-instructions
{
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4500,
      "tip": { "type": "fixedAmount", "mode": "prompted", "amount": 499 },
      "taxes": [ { "rate": 0.08, "name": "Sales Tax" } ]
    }
  },
  "customizationOptions": { "entryMethod": "deviceRead" },
  "autoCapture": true
}

主な選択項目（列挙値とフィールドの詳細はリファレンスで確認してください）：

• amount は注文の currency（ISO 4217）で指定する整数のセント単位の金額です。4999 は $49.99 です。小数は送信しないでください。
• 売上、事前承認、精算の違い： autoCapture: true（デフォルト）= 売上、autoCapture: false = 事前承認（後でキャプチャ）、processAsSale: true は即時に精算し、autoCapture を無視します。意図的に選択してください。
• entryMethod のデフォルトは deviceRead です。他の値はリファレンスで確認し、値を勝手に作らないでください。
• 売上時にトークン化するには credentialOnFile.tokenize: true を指定します（加盟店起点の後続処理には mitAgreement も指定します）。

---

ステップ 4 — 拡張（署名、返金、取消）

手順については references/narrative-extend.md を、データ構造については references/api-schema.md を参照してください。

• 署名を取得する — 決済には紐づかない単独の処理です。{ "processingTerminalId": "…" } を /signature-instructions に送信してポーリングし、その後 signature リンクをたどって GET /signatures/{id} を呼び出し、 Base64 の signature（その contentType、例：image/png）をデコードします。
• 参照なしの返金 — デバイスへの指示です：POST /devices/{serialNumber}/refund-instructions。 返金注文では order.description が必須です。ポーリング → リンクをたどる → GET /refunds/{id}。
• 参照ありの返金 — デバイスへの指示ではありません。標準の決済 API を使い、元の paymentId が必要です。 GET /payments/{paymentId} または GET /payments（last4、 cardholderName、orderId、dateFrom／dateTo、…）で取得してから、{ amount, currency } を指定して POST /payments/{paymentId}/refunds を呼び出します。
• 決済を取り消す — こちらも決済 API を使います。まだオープンバッチにある決済に対して、 POST /payments/{paymentId}/reverse を呼び出します（全額の場合は amount を省略し、一部の場合は指定します）。資金は移動しません。
• 取消と返金の違い： オープンバッチで、まだ資金が引き落とされていない場合 → 取消；すでに精算済みの場合 → 返金。 注意：オープンバッチの決済に対して参照ありの返金を行うと、返金は作成されず、自動的に取消されます。 そのため、意図する処理を慎重に選んでください。
• クローズドループ読み取りの取得 — クローズドループの指示（MiFare カードの読み取りなど）を発行した場合は、 GET /closed-loop-reads/{id} でペイロードを取得します。data オブジェクトは非構造化（カードによって構造が異なります）です。 固定のスキーマを前提にしないでください。references/api-schema.md を参照してください。

---

冪等性

すべての指示の POST（およびすべての返金／取消の POST）では、Idempotency-Key ヘッダーに新しい UUID v4 を指定します（新規送信ごとに必要です）。送信が届いていない可能性がある場合（ネットワークの瞬断、タイムアウト）に再試行するには、バイト単位で完全に同一の本文を同じキーで再送します。ゲートウェイはデバイスに2つ目の指示を送信せず、元の結果を返します。キーを再利用して本文を変更すると 409 になります。ポーリング（GET）とキャンセル（DELETE）には冪等性キーは不要です。

---

エラーへの対応

エラーは、Payroc の errors[] 配列を拡張した RFC 7807 の問題詳細エンベロープ（type、title、status、detail、instance）を使用します。エンベロープの構造と、正規のエラー type カタログについては references/error-response-format.md を参照してください。各エラーをリクエスト本文に対応付けるには errors[].parameter を確認します。ステータスごとの表については references/api-schema.md を参照してください。

Cloud のエラー形式はまだ確認されていません。 Cloud でも一貫しているという前提で、標準の Payroc エンベロープ（オンボーディングのエンドポイントで確認済み）を適用しましたが、稼働中の Cloud アカウントでは確認できませんでした。failure の指示では errorMessage を、4xx では errors[] を確認してください。ただし、Cloud 固有のエラーテキストについて、確認できていない前提をハードコードしないでください。

ステータス	状況	対応
400	送信時の検証エラー	各 errors[].parameter を該当フィールドに対応付けて修正し、再送信します（同一内容で再試行する場合は同じ冪等性キーを再利用します）。
401	トークンの期限切れ／無効	再認証して新しいベアラートークンを取得します。
403	権限不足	API キーのスコープを確認します。
404	指示またはリソースが見つからない	ID を確認し、指示 ID とリソース ID を取り違えていないか確認します。
409	競合 — 指示がすでに inProgress ではない状態でキャンセルしようとした場合、または本文を変更して冪等性キーを再利用した場合	まず指示の現在の status を GET で確認します。むやみに再試行しないでください。
500	サーバーエラー	バックオフを適用して再試行し、errors があれば提示します。

指示レベルの結果も確認してください：ポーリングで status: "failure" の場合は errorMessage を読み取ります。status: "canceled" の場合は、完了前にキャンセルされています。

---

よくある落とし穴

• instruction id からリソース URL を合成すること。 完了した instruction には、別の id を指す link.href が含まれています。このリンクに従ってください。/payments/{paymentInstructionId} を組み立ててはいけません。
• 202（またはポーリング時の 200）を成功とみなすこと。 202 はリレーを受け付けたことを意味します。ポーリングでは status: "failure" を含む 200 が返ることがあります。販売の結果は取得した paymentに記載されています。
• ポーリングを短い間隔で繰り返すこと、または手動でスリープすること。 ゲートウェイはすでにポーリングを約60秒間ロングポーリングします。GET をそのまま待機し、まだ inProgress の場合にのみ再度実行してください。
• キャンセルが遅すぎること。 DELETE が機能するのは inProgress の間だけです。それ以外の場合は 409 になります。まず status を確認してください。
• 小数の金額を指定すること。 amount は常に整数のセント単位です。
• 列挙型の値を勝手に作ること。 entryMethod、instruction の status、currency、mitAgreement、tip.type、refund の responseCode、payment-search の status／type はすべて列挙型です。references/api-schema.md で値を確認してください。
• refund instruction で order.description を指定し忘れること。 payment とは異なり、ここでは必須です。
• 未決済バッチで refund と reverse を混同すること。 未決済バッチの payment に対する参照付き refund は、自動的に reverse します。未決済の payment をキャンセルする場合は、POST /payments/{paymentId}/reverse を使用してください。
• 冪等性キーを再利用する、または指定しないこと。 新しい送信ごとに新しい UUID を使用してください。同一のリクエスト本文を再試行する場合に限り、同じキーを使用します。GET／DELETE には指定しません。
• デバイスを「セットアップ」しようとすること。 ペアリング／設定はハードウェア側の作業であり、対象外です。このスキルは既知の serialNumber から開始します（GET /devices で検索してください）。

---

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

references/api-schema.md では、エンドポイント一覧、instruction オブジェクトとその status 列挙型、order、breakdown、credentialOnFile、customizationOptions を含む paymentInstructionRequest／refundInstructionRequest／signatureInstructionRequest スキーマ、signature および closed-loop の取得、参照付き refund と reverse のエンドポイント、GET /payments と GET /devices による検索、エラーエンベロープを確認できます。