{ "openapi": "3.1.0", "info": { "title": "SWAPay API", "version": "2026-11-07" }, "servers": [ { "url": "https://www.swapay-app.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/payment_intents": { "post": { "operationId": "payment_intents.create", "summary": "PaymentIntent を作成", "description": "支払いを作り、checkout_url を返します。お客様をその URL へ案内してください。支払いが終わると return_url に戻り、ウェブフック payment_intent.succeeded が届きます。1回だけ支払えます。", "tags": [ "決済" ], "x-scope": "payment_intents:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "object": "payment_intent", "amount": 3960, "amount_received": 0, "amount_refunded": 0, "currency": "jpy", "status": "requires_payment_method", "description": "ご注文 1029", "metadata": { "order_id": "1029" }, "checkout_url": "https://www.swapay-app.com/pay/01jbx3q4w2k8m5n6p7r8s9t0va", "next_action": { "type": "redirect_to_url", "redirect_to_url": { "url": "https://www.swapay-app.com/pay/01jbx3q4w2k8m5n6p7r8s9t0va" } }, "return_url": "https://shop.example.co.jp/thanks", "latest_charge": null, "customer": null, "payment_method": null, "last_payment_error": null, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "amount": 3960, "currency": "jpy", "description": "ご注文 1029", "metadata[order_id]": "1029", "return_url": "https://shop.example.co.jp/thanks" } }, "application/x-www-form-urlencoded": { "example": { "amount": 3960, "currency": "jpy", "description": "ご注文 1029", "metadata[order_id]": "1029", "return_url": "https://shop.example.co.jp/thanks" } } } } }, "get": { "operationId": "payment_intents.list", "summary": "PaymentIntent の一覧", "description": "新しい順に返します。", "tags": [ "決済" ], "x-scope": "payment_intents:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/payment_intents", "has_more": false, "data": [ { "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "object": "payment_intent", "amount": 3960, "amount_received": 0, "amount_refunded": 0, "currency": "jpy", "status": "requires_payment_method", "description": "ご注文 1029", "metadata": { "order_id": "1029" }, "checkout_url": "https://www.swapay-app.com/pay/01jbx3q4w2k8m5n6p7r8s9t0va", "next_action": { "type": "redirect_to_url", "redirect_to_url": { "url": "https://www.swapay-app.com/pay/01jbx3q4w2k8m5n6p7r8s9t0va" } }, "return_url": "https://shop.example.co.jp/thanks", "latest_charge": null, "customer": null, "payment_method": null, "last_payment_error": null, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } } ] } }, "/payment_intents/{id}": { "get": { "operationId": "payment_intents.retrieve", "summary": "PaymentIntent を取得", "description": "今の状態を返します。", "tags": [ "決済" ], "x-scope": "payment_intents:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "object": "payment_intent", "amount": 3960, "amount_received": 3960, "amount_refunded": 0, "currency": "jpy", "status": "succeeded", "description": "ご注文 1029", "metadata": { "order_id": "1029" }, "checkout_url": null, "next_action": null, "return_url": "https://shop.example.co.jp/thanks", "latest_charge": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "customer": null, "payment_method": null, "last_payment_error": null, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/payment_intents/{id}/cancel": { "post": { "operationId": "payment_intents.cancel", "summary": "PaymentIntent を取消", "description": "支払い前の PaymentIntent を取り消します（決済画面で支払えなくなります）。支払い済みのものは取消返金を使ってください。", "tags": [ "決済" ], "x-scope": "payment_intents:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "object": "payment_intent", "amount": 3960, "amount_received": 0, "amount_refunded": 0, "currency": "jpy", "status": "canceled", "description": "ご注文 1029", "metadata": { "order_id": "1029" }, "checkout_url": null, "next_action": null, "return_url": "https://shop.example.co.jp/thanks", "latest_charge": null, "customer": null, "payment_method": null, "last_payment_error": null, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ] } }, "/charges": { "get": { "operationId": "charges.list", "summary": "Charge の一覧", "description": "新しい順に返します。", "tags": [ "決済" ], "x-scope": "charges:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/charges", "has_more": false, "data": [ { "id": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "object": "charge", "amount": 3960, "amount_refunded": 0, "currency": "jpy", "status": "succeeded", "reference": "SP-C3D4E5F6G7", "payment_method_type": "card", "channel": "api", "card": { "brand": "visa", "last4": "4242", "issuer_country": "JP" }, "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "paid_at": "2026-10-28T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "受付経路で絞り込み", "schema": { "type": "string" } }, { "name": "payment_intent", "in": "query", "required": false, "description": "PaymentIntent で絞り込み", "schema": { "type": "string" } } ] } }, "/charges/{id}": { "get": { "operationId": "charges.retrieve", "summary": "Charge を取得", "description": "", "tags": [ "決済" ], "x-scope": "charges:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "object": "charge", "amount": 3960, "amount_refunded": 0, "currency": "jpy", "status": "succeeded", "reference": "SP-C3D4E5F6G7", "payment_method_type": "card", "channel": "api", "card": { "brand": "visa", "last4": "4242", "issuer_country": "JP" }, "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "paid_at": "2026-10-28T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/refunds": { "post": { "operationId": "refunds.create", "summary": "取消返金を作成", "description": "決済済みの支払いを取消返金します。合計は決済額を超えられません。決済代行会社での処理が終わるまで status は pending、終わると refund.succeeded が届きます。加盟店画面の設定で「○円以上はオーナーの承認」にしている場合は requires_approval になり、オーナーの承認後に処理します。", "tags": [ "取消返金" ], "x-scope": "refunds:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "re_01jbx4a2b3c4d5e6f7g8h9j0k1", "object": "refund", "amount": 1000, "currency": "jpy", "status": "pending", "reason": "customer_request", "charge": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "failure_reason": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "amount": 1000 } }, "application/x-www-form-urlencoded": { "example": { "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "amount": 1000 } } } } }, "get": { "operationId": "refunds.list", "summary": "取消返金の一覧", "description": "", "tags": [ "取消返金" ], "x-scope": "refunds:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/refunds", "has_more": false, "data": [ { "id": "re_01jbx4a2b3c4d5e6f7g8h9j0k1", "object": "refund", "amount": 1000, "currency": "jpy", "status": "pending", "reason": "customer_request", "charge": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "failure_reason": null, "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "charge", "in": "query", "required": false, "description": "決済で絞り込み", "schema": { "type": "string" } } ] } }, "/refunds/{id}": { "get": { "operationId": "refunds.retrieve", "summary": "取消返金を取得", "description": "status：pending / requires_approval / succeeded / failed / canceled（承認されなかった）", "tags": [ "取消返金" ], "x-scope": "refunds:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "re_01jbx4a2b3c4d5e6f7g8h9j0k1", "object": "refund", "amount": 1000, "currency": "jpy", "status": "succeeded", "reason": "customer_request", "charge": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "payment_intent": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "failure_reason": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/payment_links": { "post": { "operationId": "payment_links.create", "summary": "リンク決済を作成", "description": "メールや SNS で送る決済ページを作ります。何人でも支払えます（max_uses で上限）。", "tags": [ "受付" ], "x-scope": "payment_links:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "plink_01jbx4m1n2p3q4r5s6t7v8w9x0", "object": "payment_link", "title": "11月 セミナー参加費", "description": null, "amount": 5500, "customer_enters_amount": false, "min_amount": null, "max_amount": null, "currency": "jpy", "active": true, "url": "https://www.swapay-app.com/pay/01jbx4m1n2p3q4r5s6t7v8w9x0", "max_uses": 100, "times_paid": 0, "expires_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "title": "11月 セミナー参加費", "amount": 5500, "max_uses": 100 } }, "application/x-www-form-urlencoded": { "example": { "title": "11月 セミナー参加費", "amount": 5500, "max_uses": 100 } } } } } }, "/payment_links/{id}": { "get": { "operationId": "payment_links.retrieve", "summary": "リンク決済を取得・一覧", "description": "一覧は GET /payment_links（limit・starting_after）。", "tags": [ "受付" ], "x-scope": "payment_links:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "plink_01jbx4m1n2p3q4r5s6t7v8w9x0", "object": "payment_link", "title": "11月 セミナー参加費", "description": null, "amount": 5500, "customer_enters_amount": false, "min_amount": null, "max_amount": null, "currency": "jpy", "active": true, "url": "https://www.swapay-app.com/pay/01jbx4m1n2p3q4r5s6t7v8w9x0", "max_uses": 100, "times_paid": 0, "expires_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "payment_links.update", "summary": "リンク決済を更新", "description": "指定した項目だけ変えます。受付を止めるときは POST /payment_links/{id}/deactivate。", "tags": [ "受付" ], "x-scope": "payment_links:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "plink_01jbx4m1n2p3q4r5s6t7v8w9x0", "object": "payment_link", "title": "11月 セミナー参加費", "description": null, "amount": 5500, "customer_enters_amount": false, "min_amount": null, "max_amount": null, "currency": "jpy", "active": true, "url": "https://www.swapay-app.com/pay/01jbx4m1n2p3q4r5s6t7v8w9x0", "max_uses": 150, "times_paid": 0, "expires_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "max_uses": 150 } }, "application/x-www-form-urlencoded": { "example": { "max_uses": 150 } } } } } }, "/qr_codes": { "post": { "operationId": "qr_codes.create", "summary": "QRコードを作成", "description": "店頭に置く QR コードです。customer_enters_amount=true で、支払う人が金額を入れます。画像は image_url（SVG）。取得・一覧・更新・停止は /payment_links と同じ形です。", "tags": [ "受付" ], "x-scope": "payment_links:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "qr_01jbx4q8r7s6t5v4w3x2y1z0a9", "object": "qr_code", "title": "レジ横", "description": null, "amount": null, "customer_enters_amount": true, "min_amount": 100, "max_amount": 50000, "currency": "jpy", "active": true, "url": "https://www.swapay-app.com/pay/01jbx4q8r7s6t5v4w3x2y1z0a9", "max_uses": null, "times_paid": 0, "expires_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false, "image_url": "https://www.swapay-app.com/api/v1/qr_codes/qr_01jbx4q8r7s6t5v4w3x2y1z0a9/image.svg" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "title": "レジ横", "customer_enters_amount": true, "max_amount": 50000 } }, "application/x-www-form-urlencoded": { "example": { "title": "レジ横", "customer_enters_amount": true, "max_amount": 50000 } } } } } }, "/invoices": { "post": { "operationId": "invoices.create", "summary": "請求書を作成", "description": "適格請求書の形（税率ごとに消費税を1回だけ端数処理）で作ります。send=true ですぐ請求先へメールします。", "tags": [ "請求書" ], "x-scope": "invoices:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "in_01jbx5a1s2d3f4g5h6j7k8l9m0", "object": "invoice", "number": "INV-2026-00012", "title": "10月分 ご利用料金", "status": "open", "overdue": false, "customer": { "name": "山田 太郎", "company": "株式会社サンプル", "email": "billing@example.co.jp" }, "lines": [ { "name": "月額利用料", "unit_amount": 10000, "quantity": 1, "tax_rate": 10 } ], "subtotal": 10000, "tax": { "10": 1000, "8": 0 }, "total": 11000, "currency": "jpy", "issue_date": "2026-10-28", "due_date": "2026-11-30", "hosted_url": "https://www.swapay-app.com/pay/01jbx5…/invoice", "payment_url": "https://www.swapay-app.com/pay/01jbx5…", "sent_at": "2026-10-28T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "customer": { "name": "山田 太郎", "email": "billing@example.co.jp" }, "title": "10月分 ご利用料金", "lines": [ { "name": "月額利用料", "unit_amount": 10000, "quantity": 1, "tax_rate": 10 } ], "due_date": "2026-11-30", "send": true } }, "application/x-www-form-urlencoded": { "example": { "customer": { "name": "山田 太郎", "email": "billing@example.co.jp" }, "title": "10月分 ご利用料金", "lines": [ { "name": "月額利用料", "unit_amount": 10000, "quantity": 1, "tax_rate": 10 } ], "due_date": "2026-11-30", "send": true } } } } } }, "/invoices/{id}/send": { "post": { "operationId": "invoices.send", "summary": "請求書を送信・無効にする", "description": "下書きを送ります（送信済みならメールだけ送り直し）。無効にするときは POST /invoices/{id}/void。取得・一覧は GET /invoices/{id}・GET /invoices。status：draft / open / paid / void（期限切れは overdue=true）", "tags": [ "請求書" ], "x-scope": "invoices:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "in_01jbx5a1s2d3f4g5h6j7k8l9m0", "object": "invoice", "number": "INV-2026-00012", "title": "10月分 ご利用料金", "status": "open", "overdue": false, "customer": { "name": "山田 太郎", "company": "株式会社サンプル", "email": "billing@example.co.jp" }, "lines": [ { "name": "月額利用料", "unit_amount": 10000, "quantity": 1, "tax_rate": 10 } ], "subtotal": 10000, "tax": { "10": 1000, "8": 0 }, "total": 11000, "currency": "jpy", "issue_date": "2026-10-28", "due_date": "2026-11-30", "hosted_url": "https://www.swapay-app.com/pay/01jbx5…/invoice", "payment_url": "https://www.swapay-app.com/pay/01jbx5…", "sent_at": "2026-10-28T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ] } }, "/prices": { "get": { "operationId": "prices.list", "summary": "料金プラン（Price）の一覧", "description": "加盟店画面で作ったプランです（作成・変更は加盟店画面で行います）。1件は GET /prices/{id}。", "tags": [ "サブスクリプション" ], "x-scope": "subscriptions:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/prices", "has_more": false, "data": [ { "id": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "object": "price", "code": "BEANS200", "name": "コーヒー豆 定期便 200g", "description": "焙煎したての豆を毎月お届けします。", "unit_amount": 2980, "tax_behavior": "inclusive", "tax_rate": 10, "currency": "jpy", "recurring": { "interval": "month", "interval_count": 1, "billing_anchor": "day:25" }, "trial": null, "setup_fee": 0, "max_count": null, "min_term_months": null, "active": true, "signup_url": "https://www.swapay-app.com/pay/01jbx6…", "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } } ] } }, "/subscriptions": { "post": { "operationId": "subscriptions.create", "summary": "申込ページの URL を作る", "description": "お客様をこの URL へ案内してください。お客様が SWAPay の申込ページで内容に同意し、カードを登録すると契約ができ、subscription.created が届きます（カードの登録と同意はお客様の操作が必要なため、API だけで契約は作れません）。", "tags": [ "サブスクリプション" ], "x-scope": "subscriptions:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "object": "subscription_checkout", "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "quantity": 1, "url": "https://www.swapay-app.com/pay/01jbx6…?email=user%40example.com", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "customer_email": "user@example.com" } }, "application/x-www-form-urlencoded": { "example": { "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "customer_email": "user@example.com" } } } } } }, "/subscriptions/{id}": { "get": { "operationId": "subscriptions.retrieve", "summary": "サブスクリプションを取得・一覧", "description": "status：trialing / active / past_due（支払い遅延）/ paused / canceling（解約予定）/ canceled。一覧は GET /subscriptions（status・price で絞り込み）。", "tags": [ "サブスクリプション" ], "x-scope": "subscriptions:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "sub_01jbx7s1u2b3s4c5r6i7p8t9n0", "object": "subscription", "status": "active", "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "quantity": 1, "customer": { "email": "user@example.com", "phone": "09012345678" }, "card": { "brand": "visa", "last4": "4242" }, "next_billing_date": "2026-11-25", "cancel_at": null, "canceled_at": null, "paused_at": null, "amount_overdue": 0, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "subscriptions.cancel", "summary": "解約", "description": "at_period_end=true（既定）で、次回請求日の前日まで利用でき、以降は請求しません。false ですぐ解約（取消返金はしません）。", "tags": [ "サブスクリプション" ], "x-scope": "subscriptions:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "sub_01jbx7s1u2b3s4c5r6i7p8t9n0", "object": "subscription", "status": "canceling", "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "quantity": 1, "customer": { "email": "user@example.com", "phone": "09012345678" }, "card": { "brand": "visa", "last4": "4242" }, "next_billing_date": "2026-11-25", "cancel_at": "2026-11-25", "canceled_at": null, "paused_at": null, "amount_overdue": 0, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "at_period_end": true } }, "application/x-www-form-urlencoded": { "example": { "at_period_end": true } } } } } }, "/subscriptions/{id}/pause": { "post": { "operationId": "subscriptions.pause", "summary": "一時停止・再開", "description": "一時停止中は請求しません（未払いの再決済・催促もしません）。再開は POST /subscriptions/{id}/resume（止めていた期間の日割りはしません）。", "tags": [ "サブスクリプション" ], "x-scope": "subscriptions:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "sub_01jbx7s1u2b3s4c5r6i7p8t9n0", "object": "subscription", "status": "paused", "price": "price_01jbx6p1r2i3c4e5x6y7z8a9b0", "quantity": 1, "customer": { "email": "user@example.com", "phone": "09012345678" }, "card": { "brand": "visa", "last4": "4242" }, "next_billing_date": null, "cancel_at": null, "canceled_at": null, "paused_at": "2026-10-28T03:15:42Z", "amount_overdue": 0, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "resume_on": "2026-12-01" } }, "application/x-www-form-urlencoded": { "example": { "resume_on": "2026-12-01" } } } } } }, "/setup_sessions": { "post": { "operationId": "setup_sessions.create", "summary": "カードの登録ページを作る（SetupSession）", "description": "お客様にカードを登録してもらうページを作ります（予約のキャンセル料・あとで決まる料金のため）。お客様は url のページで電話番号を確認し、使い道（description）と1回の上限（max_amount）に同意して、決済代行会社の入力欄にカードを入れます（カード番号はあなたのサーバーも SWAPay も通りません）。確認のため max_amount の利用枠を 3D セキュアつきで一時的に確保し、すぐに取り消します。登録できると status=complete・payment_method に pm_ が入り、ウェブフック setup_session.completed が届きます。決済代行会社の継続課金の利用が必要です。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "object": "setup_session", "status": "open", "url": "https://www.swapay-app.com/pay/01jbxb1s2e3t4u5p6s7e8s9n0a", "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "max_amount": 6600, "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "payment_method": null, "return_url": "https://salon.example.co.jp/reserve/done", "metadata": { "reservation_id": "R-2041" }, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "max_amount": 6600, "currency": "jpy", "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "return_url": "https://salon.example.co.jp/reserve/done", "metadata[reservation_id]": "R-2041" } }, "application/x-www-form-urlencoded": { "example": { "max_amount": 6600, "currency": "jpy", "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "return_url": "https://salon.example.co.jp/reserve/done", "metadata[reservation_id]": "R-2041" } } } } }, "get": { "operationId": "setup_sessions.list", "summary": "SetupSession の一覧", "description": "新しい順に返します。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/setup_sessions", "has_more": false, "data": [ { "id": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "object": "setup_session", "status": "open", "url": "https://www.swapay-app.com/pay/01jbxb1s2e3t4u5p6s7e8s9n0a", "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "max_amount": 6600, "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "payment_method": null, "return_url": "https://salon.example.co.jp/reserve/done", "metadata": { "reservation_id": "R-2041" }, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "顧客で絞り込み", "schema": { "type": "string" } } ] } }, "/setup_sessions/{id}": { "get": { "operationId": "setup_sessions.retrieve", "summary": "SetupSession を取得・一覧・取消", "description": "status：open（登録待ち）/ complete（登録済み）/ expired / canceled。一覧は GET /setup_sessions（customer で絞り込み）。登録前のページは POST /setup_sessions/{id}/cancel で取り消せます。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "object": "setup_session", "status": "complete", "url": null, "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "max_amount": 6600, "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "payment_method": "pm_01jbxc1p2m3e4t5h6o7d8a9b0c", "return_url": "https://salon.example.co.jp/reserve/done", "metadata": { "reservation_id": "R-2041" }, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/setup_sessions/{id}/cancel": { "post": { "operationId": "setup_sessions.cancel", "summary": "SetupSession を取消", "description": "登録前のページを取り消します（登録済みなら 409。登録カードは detach で削除）。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "object": "setup_session", "status": "canceled", "url": null, "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "max_amount": 6600, "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "payment_method": null, "return_url": "https://salon.example.co.jp/reserve/done", "metadata": { "reservation_id": "R-2041" }, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ] } }, "/payment_methods": { "get": { "operationId": "payment_methods.list", "summary": "PaymentMethod の一覧・取得", "description": "新しい順に返します。1件は GET /payment_methods/{id}。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/payment_methods", "has_more": false, "data": [ { "id": "pm_01jbxc1p2m3e4t5h6o7d8a9b0c", "object": "payment_method", "type": "card", "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2029 }, "status": "active", "max_amount": 6600, "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "setup_session": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "metadata": { "reservation_id": "R-2041" }, "last_used_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "顧客で絞り込み", "schema": { "type": "string" } }, { "name": "setup_session", "in": "query", "required": false, "description": "SetupSession で絞り込み", "schema": { "type": "string" } } ] } }, "/payment_methods/{id}": { "get": { "operationId": "payment_methods.retrieve", "summary": "PaymentMethod を取得", "description": "", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "pm_01jbxc1p2m3e4t5h6o7d8a9b0c", "object": "payment_method", "type": "card", "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2029 }, "status": "active", "max_amount": 6600, "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "setup_session": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "metadata": { "reservation_id": "R-2041" }, "last_used_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/payment_methods/{id}/detach": { "post": { "operationId": "payment_methods.detach", "summary": "PaymentMethod を削除", "description": "登録カードを削除します（決済代行会社のトークンも無効にします）。元に戻せません。", "tags": [ "顧客・カードの登録" ], "x-scope": "payment_methods:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "pm_01jbxc1p2m3e4t5h6o7d8a9b0c", "object": "payment_method", "type": "card", "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2029 }, "status": "detached", "max_amount": 6600, "description": "11/30 カット 予約のキャンセル料（前日 50%・当日 100%）", "currency": "jpy", "customer": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "setup_session": "seti_01jbxb1s2e3t4u5p6s7e8s9n0a", "metadata": { "reservation_id": "R-2041" }, "last_used_at": null, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ] } }, "/customers": { "post": { "operationId": "customers.create", "summary": "顧客を作成", "description": "加盟店画面の顧客管理と同じお客様です（顧客管理が使えるプラン：mPOS かストアのプロ）。同じメール・電話のお客様がいれば、新しく作らずにそのお客様を返します（200）。メール・電話は暗号化して保管します。", "tags": [ "顧客・カードの登録" ], "x-scope": "customers:write", "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "object": "customer", "name": "山田 太郎", "email": "taro@example.com", "phone": "09012345678", "metadata": { "member_no": "A-102" }, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "name": "山田 太郎", "email": "taro@example.com", "phone": "090-1234-5678", "metadata[member_no]": "A-102" } }, "application/x-www-form-urlencoded": { "example": { "name": "山田 太郎", "email": "taro@example.com", "phone": "090-1234-5678", "metadata[member_no]": "A-102" } } } } }, "get": { "operationId": "customers.list", "summary": "顧客の一覧", "description": "新しい順に返します。email・phone は完全一致で探します。", "tags": [ "顧客・カードの登録" ], "x-scope": "customers:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/customers", "has_more": false, "data": [ { "id": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "object": "customer", "name": "山田 太郎", "email": "taro@example.com", "phone": "09012345678", "metadata": { "member_no": "A-102" }, "created": "2026-10-28T03:15:42Z", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "メールアドレス（完全一致）", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "description": "電話番号（完全一致）", "schema": { "type": "string" } } ] } }, "/customers/{id}": { "get": { "operationId": "customers.retrieve", "summary": "顧客を取得", "description": "", "tags": [ "顧客・カードの登録" ], "x-scope": "customers:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "object": "customer", "name": "山田 太郎", "email": "taro@example.com", "phone": "09012345678", "metadata": { "member_no": "A-102" }, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "customers.update", "summary": "顧客を更新", "description": "指定した項目だけ変えます。ほかのお客様と同じメール・電話にはできません（409 customer_exists）。", "tags": [ "顧客・カードの登録" ], "x-scope": "customers:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "object": "customer", "name": "山田 太郎", "email": "taro@example.com", "phone": "09012345678", "metadata": { "member_no": "A-102" }, "created": "2026-10-28T03:15:42Z", "livemode": false } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "example": { "name": "山田 太郎" } }, "application/x-www-form-urlencoded": { "example": { "name": "山田 太郎" } } } } }, "delete": { "operationId": "customers.delete", "summary": "顧客を削除", "description": "お客様の情報を消し、そのお客様の登録カードも削除します（取扱高の集計は残ります）。元に戻せません。", "tags": [ "顧客・カードの登録" ], "x-scope": "customers:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "id": "cus_01jbxa1c2u3s4t5o6m7e8r9a0b", "object": "customer", "deleted": true } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "同じ値で再送すると最初の結果を返す（7日）", "schema": { "type": "string", "maxLength": 255 } } ] } }, "/settlements": { "get": { "operationId": "settlements.list", "summary": "精算の一覧・取得", "description": "締めた期間ごとの取扱高・取消返金・手数料・入金額です。1件は GET /settlements/{id}。", "tags": [ "精算" ], "x-scope": "settlements:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/settlements", "has_more": false, "data": [ { "id": "stl_01jbx8s1e2t3t4l5e6m7e8n9t0", "object": "settlement", "period_start": "2026-10-01", "period_end": "2026-10-15", "payout_date": "2026-10-31", "payout_route": "swapay", "transaction_count": 128, "gross": 412800, "refunds": 3960, "fees": 13374, "carry_over": 0, "net": 395466, "status": "unpaid", "paid_at": null, "currency": "jpy", "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } } ] } }, "/events": { "get": { "operationId": "events.list", "summary": "イベントの一覧・取得", "description": "30日分を新しい順に返します。ウェブフックを受け取れなかったときの確認に使えます。1件は GET /events/{id}。", "tags": [ "イベント" ], "x-scope": "events:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "object": "list", "url": "/v1/events", "has_more": false, "data": [ { "id": "evt_01jbx9e1v2e3n4t5a6b7c8d9e0", "object": "event", "type": "payment_intent.succeeded", "api_version": "2026-11-07", "created": "2026-10-28T03:15:42Z", "data": { "object": { "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va", "object": "payment_intent", "amount": 3960, "amount_received": 3960, "amount_refunded": 0, "currency": "jpy", "status": "succeeded", "description": "ご注文 1029", "metadata": { "order_id": "1029" }, "checkout_url": null, "next_action": null, "return_url": "https://shop.example.co.jp/thanks", "latest_charge": "ch_01jbx3t9a1b2c3d4e5f6g7h8j9", "customer": null, "payment_method": null, "last_payment_error": null, "expires_at": "2026-10-29T03:15:42Z", "created": "2026-10-28T03:15:42Z", "livemode": false } }, "livemode": false } ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1〜100（既定 20）", "schema": { "type": "integer" } }, { "name": "starting_after", "in": "query", "required": false, "description": "前のページの最後の ID。次のページを取るときに指定", "schema": { "type": "string" } }, { "name": "created[gte]", "in": "query", "required": false, "description": "作成日時（RFC 3339 か UNIX 秒）以降。gt・lt・lte も使えます", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "イベントの種類で絞り込み", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "シークレットキー（sk_live_… / sk_test_…）または制限付きキー（rk_…）" } }, "responses": { "Error": { "description": "エラー", "content": { "application/json": { "example": { "error": { "type": "invalid_request", "code": "parameter_invalid", "message": "amount は 1 以上にしてください。", "param": "amount", "retryable": false, "request_id": "req_01jbx…" } } } } } } } }