SWAPay CODE

SWAPay APIREST · JSON · v1SWAPay-Version 2026-11-07

決済を、
数行のコードで。

PaymentIntent を1つ作って、返ってきた checkout_url にお客様を案内するだけ。カード番号は、あなたのサーバーも SWAPay も通りません。結果は署名つきのウェブフックで届きます。

pi_01jbx3q4w2k8m5n6p7r8s9t0varequires_payment_method
あなたのサーバーPOST /payment_intents
$ curl https://www.swapay-app.com/api/v1/payment_intents \    -H "Authorization: Bearer sk_test_…" \    -H "Idempotency-Key: order-1029" \    -d amount=3300 -d currency=jpy
HTTP/1.1 201 Created{  "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va",  "object": "payment_intent",  "amount": 3300,  "status": "requires_payment_method",  "checkout_url": "https://www.swapay-app.com/pay/01jbx3q4w2k8m5n6p7r8s9t0va"}
お客様のスマートフォンcheckout_url
お客様の支払い画面:支払内容:お店の名前と金額
あなたのサーバー(ウェブフック)POST /webhooks/swapay
SWAPay-Signature: t=1762761600,v1=5f2c9a…
{
    "id": "evt_01jbx9e1v2e3n4t5a6b7c8d9e0",
    "type": "payment_intent.succeeded",
    "data": {
        "object": {
            "id": "pi_01jbx3q4w2k8m5n6p7r8s9t0va",
            "amount": 3300,
            "status": "succeeded"
        }
    }
}
200 OK · 署名を確認しました
サンプルです(スマートフォンは実際の決済画面をデモデータで撮ったもの)。
34エンドポイント
HMACウェブフックの署名(SHA-256)
7日Idempotency-Key の有効期間
16回ウェブフックの送り直し(最大)

料金

API の利用料は、かかりません。
かかるのは決済手数料だけ。

決済手数料(基本)
3.24%

消費税込み。API からの決済も、QR コード・リンク・店頭レジからの決済も同じ率です。

業種・業態により
1.9%〜

業種・業態と審査の結果によって、ご契約の率が決まります。取扱高の多い事業者さまはご相談ください。

0円API の利用料
0円初期費用・月額(API・リンク・請求書・サブスクリプション)
0円検証用のキー(sk_test_)での試験
220円SWAPay からの振込手数料(1回)

店頭レジ・オンラインストアの月額プランなど、料金の詳しい内容は SWAPay PLUS の料金 をご覧ください。

はじめ方

作って、案内して、受け取る。

加盟店画面の「API管理」でキーを発行したら、あとは3つだけ。検証用のキー(sk_test_)なら、本番のお金を動かさずに最後まで試せます。

create_payment.sh
curl https://www.swapay-app.com/api/v1/payment_intents \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order-1029" \
  -d amount=3300 \
  -d currency=jpy \
  -d description="ご注文 1029" \
  -d "metadata[order_id]=1029" \
  -d return_url=https://shop.example.co.jp/thanks

エンドポイント https://www.swapay-app.com/api/v1 すべてのリクエストに Authorization: Bearer <キー>

PaymentIntent の状態

ひとつの決済は、ひとつのオブジェクトで追えます。

1requires_payment_method

作った直後。お客様が決済画面でお支払い方法を選ぶのを待っています。

2requires_action

3D セキュアの認証中。お客様の操作を待っています。

3processing

スマホ決済などの結果待ち。届きしだい次へ進みます。

✓succeeded

支払い完了。payment_intent.succeeded が届きます。

期限を過ぎたもの・取り消したものは canceled。取消返金は /refunds で、全額でも一部でも。

ウェブフック・送り直し

通信が切れても、取りこぼさない。
二重にも決済しない。

  • 署名つきで届くヘッダー SWAPay-Signature の v1 と、「t.本文」を署名用シークレットで HMAC-SHA256 した値を比べます。時刻が5分以上ずれていれば受け付けないでください。
  • 2xx を返すまで送り直す同じイベントは同じ id で届くので、id で重複を除いてください。届かなかったときは GET /events で30日分を確かめられます。
  • Idempotency-Key で二重決済を防ぐPOST に付けると、同じ値で送り直したときは最初の結果を返します(7日間)。違う内容で同じキーを使うとエラーで止まります。
  • エラーは同じ形で決済代行会社の生のエラーは返しません。retryable が true のときだけ、同じ Idempotency-Key で送り直してください。
同じ Idempotency-Key で2回送ったとき同じ結果
POST /payment_intents Idempotency-Key: order-1029 → 201 pi_01jbx3q4w2k8m5n6p7r8s9t0va
=
POST /payment_intents Idempotency-Key: order-1029 → 201 pi_01jbx3q4w2k8m5n6p7r8s9t0va
エラーの形400 Bad Request
{
    "error": {
        "type": "invalid_request",
        "code": "parameter_invalid",
        "message": "amount は 1 以上にしてください。",
        "param": "amount",
        "retryable": false,
        "request_id": "req_01jbx…"
    }
}

送り直しの間隔

2xx が返らないときは、間隔をあけて最大16回送ります。最後の送り直しは、1回目の52時間51分後です。

時間の目盛りは対数です(はじめは短い間隔で、だんだん長く)。

API の一覧

決済のあとまで、API で。

加盟店画面でできることの多くを、あなたのシステムから。項目の詳しい説明は API リファレンスと OpenAPI をご覧ください。

6 endpoints

決済

  • POST/payment_intents
  • GET/payment_intents/{id}
  • GET/payment_intents
  • POST/payment_intents/{id}/cancel
  • GET/charges
  • ほか 1
3 endpoints

取消返金

  • POST/refunds
  • GET/refunds/{id}
  • GET/refunds
4 endpoints

リンク決済・QR コード

  • POST/payment_links
  • GET/payment_links/{id}
  • POST/payment_links/{id}
  • POST/qr_codes
2 endpoints

請求書

  • POST/invoices
  • POST/invoices/{id}/send
5 endpoints

サブスクリプション

  • GET/prices
  • POST/subscriptions
  • GET/subscriptions/{id}
  • POST/subscriptions/{id}/cancel
  • POST/subscriptions/{id}/pause
12 endpoints

顧客・カードの登録

  • POST/setup_sessions
  • GET/setup_sessions/{id}
  • GET/setup_sessions
  • POST/setup_sessions/{id}/cancel
  • GET/payment_methods
  • ほか 7
1 endpoints

精算

  • GET/settlements
1 endpoints

イベント

  • GET/events
sk_test_

検証環境のキー。本番のお金を動かさずに試せます。本番と検証のキーを取り違えるとエラーで止まります。

sk_live_

本番のキー。発行したときに一度だけ表示し、SWAPay はハッシュだけを保存します。使える IP アドレスを絞れます。

rk_

権限を絞った制限付きキー。読み取りだけ・決済だけ、など用途ごとに分けられます。

応答の形はキーを作った日の版(SWAPay-Version)に固定されます。いまの版は 2026-11-07。OpenAPI(JSON)

まずは検証用のキーで。

加盟店のお申し込みがお済みでない方は、SWAPay PLUS からお申し込みください。

API リファレンス → 加盟店のお申し込み
旧 API(LTS 版)をお使いの方へ 旧 API の資料は LTS 版 API ドキュメント にあります。新しい API へ移るには、キーの発行し直しが必要です。 移行のご相談は support@swa-pay.com まで。
旧 API との違い
旧 API新しい API
POST /v1/order → payment_urlPOST /payment_intents → checkout_url
Authorization: <キー>Authorization: Bearer sk_…
金額は小数(1000.0)金額は整数(1000)
注文ごとの callback_url署名つきのウェブフック
カード番号を API で送る決済決済画面で入力(API では受け付けません)