---
title: "PayPay APIの実装手順：OPAのサンドボックス・QRコード決済・HMAC認証をNode.jsで解説"
url: "https://www.issoh.co.jp/tech/details/19875/"
published: 2026-11-16
updated: 2026-11-16
categories: ["開発"]
publisher: "株式会社一創"
---

# PayPay APIの実装手順：OPAのサンドボックス・QRコード決済・HMAC認証をNode.jsで解説

PayPay APIは、PayPayと加盟店契約を結んだ事業者が、自社のECサイトやアプリからPayPay決済を呼び出すための「PayPayオープン決済API（OPA）」を指します。決済コードを作ってPayPayの画面へ顧客を送り、支払い結果をAPIかWebhookで受け取るのが基本の流れです。この記事では、加盟店登録とサンドボックスの準備、Node.js SDKでのQRコード作成、SDKを使わないHMAC認証の組み立て、キャンセルと返金の期限、決済代行経由との選び分けまでを、2026年11月時点の公式ドキュメントをもとに解説します。

## まとめ｜PayPay API（OPA）で決済を組み込む前提・実装手順・判断基準

PayPay APIを本番で使うには、PayPayの加盟店登録が先に必要です。開発はPayPay for Developersのサンドボックスで始められ、本番と同じエンドポイント構成で決済の流れを試せます。

ECサイトの実装はウェブペイメントが基本です。サーバーで`POST /v2/codes`を呼んで決済URLを受け取り、顧客をPayPayへ送り、戻ってきたら決済詳細取得APIで状態を確かめます。戻り先ページだけで注文を確定させず、ポーリングかWebhookで`COMPLETED`を確認してから在庫や配送を動かします。

すでにStripeやPAY.JPでカード決済を運用しているなら、決済代行経由のほうが実装も契約も軽くなります。PayPayと直接契約してOPAを組むのは、手数料や入金をPayPayと直接管理したい場合や、出荷時の売上確定を使いたい場合です。

## PayPay APIを使う前に済ませる加盟店登録とサンドボックスの準備

コードを書く前に、契約・認証情報・接続先の3つを整理します。ここを取り違えると、実装が正しくても本番で`UNAUTHORIZED`が返ります。

### OPAの利用に必要な加盟店登録と発行されるAPIキー・Webhook設定

[PayPay公式のウェブペイメントの仕様書](https://www.paypay.ne.jp/opa/doc/jp/v1.0/webcashier)は、OPAを使い始める条件として、定められたプロセスでPayPay加盟店の登録を済ませることを挙げています。登録後に発行・設定されるのは、APIキーとAPIキーシークレット、Webhookの通知先、APIを呼び出す側のクライアントIPのホワイトリスト、加盟店識別子です。管理はマーチャントパネルか営業担当への連絡で行います。

見落としやすい条件が2つあります。日本国外からのPayPayアプリ・Web画面へのアクセスは制限されていること、通信にはTLS 1.2以上とSNI対応が必要なことです。海外拠点のサーバーや古いランタイムから呼ぶ構成は、設計の段階で外します。店舗としての申込書類や審査の流れは[PayPayの申込・審査・入金設定の手順](https://www.issoh.co.jp/column/details/18877/)にまとめています。

### サンドボックスと本番で異なるエンドポイントと認証情報の切り替え

[動的ユーザスキャンの仕様書](https://www.paypay.ne.jp/opa/doc/jp/v1.0/dynamicqrcode)に記載された接続先は次のとおりです（2026年11月時点）。仕様書には`api.paypay.ne.jp`などの旧ドメインも残っていますが、非推奨の扱いです。

- サンドボックス：`apigw.sandbox.paypay.ne.jp`（Test Modeの加盟店ID・APIキーを使う）
- 本番：`apigw.paypay.ne.jp`（Live Modeの加盟店ID・APIキーを使う）

PayPay for Developersのヘルプセンターでは、加盟店ID・APIキー・シークレットはTest ModeとLive Modeで別の値だと案内されています。サンドボックスのテストユーザーは1アカウントにつき3件で、残高は画面のボタンで10万円ずつ追加できます。本番のWebhook通知先は加盟店側の画面では変えられず、問い合わせフォームで変更を依頼する方式です。リリース日から逆算して、Webhookの本番URLは早めに申請しておきます。

### ウェブペイメントと動的ユーザスキャンなど決済方式4種の選び方

OPAには、顧客の使う画面に合わせた複数の決済方式があります。実務での優先度順に並べると次のとおりです。

- ウェブペイメント：ECサイトから決済URLへ遷移し、スマートフォンならPayPayアプリが開く。オンライン販売はまずこれ
- 動的ユーザスキャン：決済ごとのQRコードを画面に出し、顧客のPayPayアプリで読み取る。PCブラウザの購入画面や券売機向け
- アプリコール：自社アプリからPayPayアプリを呼び出す。自社のスマホアプリがある事業向け
- ネイティブペイメント：顧客のPayPayアカウントと連携し、毎回の画面遷移なしで決済する。利用条件が加わる

ウェブペイメントと動的ユーザスキャンは、どちらも同じ`POST /v2/codes`で作るコードを使います。違いは、レスポンスの`data.url`へ遷移させるか、QRコードとして表示するかだけです。PC向けにはQRコード、スマートフォン向けには遷移と、端末で出し分ける実装がよく取られます。店舗レジで使うCPM・MPMとの違いは[QRコード決済のCPMとMPMの違い](https://www.issoh.co.jp/column/details/18120/)で整理しています。

## Node.js SDKでQRコードを作成しPayPayの決済画面へ顧客を送る手順

公式SDKはNode.js・PHP・Python・JavaがGitHubで公開されています。ここではNode.js SDKで、決済コードの作成から状態確認までを実装します。

### paypayopa-sdk-nodeの導入とSTAGING環境でのConfigure設定

[Node.js SDKのGitHubリポジトリ](https://github.com/paypay/paypayopa-sdk-node)の手順では、npmで`@paypayopa/paypayopa-sdk-node`を入れ、`Configure`にAPIキーとシークレットを渡します。サンドボックスでは`env`に`"STAGING"`を指定し、これが既定値なので省略もできます。本番では`"PROD"`です。

```
npm i @paypayopa/paypayopa-sdk-node
```

```
const PAYPAY = require('@paypayopa/paypayopa-sdk-node');

PAYPAY.Configure({
  env: process.env.PAYPAY_ENV || 'STAGING', // 本番は 'PROD'
  clientId: process.env.PAYPAY_API_KEY,
  clientSecret: process.env.PAYPAY_API_SECRET,
});
```

既定値がサンドボックスなので、本番用の環境変数を入れ忘れても起動時にはエラーになりません。本番のキーをサンドボックスへ送ることになり、決済のたびに返るのは`UNAUTHORIZED`です。起動時に`PAYPAY_ENV`とキーの組み合わせを検査する処理を入れておくと、切り替え漏れを出荷前に止められます。なお同リポジトリは、保守は限定的で更新が定期的に出るとは限らず、新機能はAPI仕様書を優先するよう注記しています。

### POST /v2/codesでmerchantPaymentIdと戻り先URLの指定実装

決済コードの作成では、`merchantPaymentId`（加盟店内で一意・最大64文字）、`amount`、`codeType`の`ORDER_QR`が必須です。ウェブペイメントでは、支払い後に戻す`redirectUrl`と、ブラウザへ戻す`WEB_LINK`か自社アプリへ戻す`APP_DEEP_LINK`のどちらかを`redirectType`に指定します。

```
const express = require('express');
const app = express();

app.post('/orders/:id/paypay', async (req, res) => {
  const order = await findOrder(req.params.id); // 金額は必ずサーバー側の注文データから取る
  const payload = {
    merchantPaymentId: order.paymentId, // 注文と1対1・最大64文字
    amount: { amount: order.total, currency: 'JPY' },
    codeType: 'ORDER_QR',
    orderDescription: order.title,
    isAuthorization: false,
    redirectUrl: `https://example.com/orders/${order.id}/complete`,
    redirectType: 'WEB_LINK',
    userAgent: req.get('User-Agent'), // 決済後に開くブラウザの指定
  };
  const response = await PAYPAY.QRCodeCreate(payload);
  const body = response.BODY;
  if (body.resultInfo.code !== 'SUCCESS') {
    console.error(response.STATUS, body.resultInfo.code);
    return res.status(502).send('PayPayの決済画面を準備できませんでした');
  }
  res.redirect(303, body.data.url); // PCではQRコード表示に切り替えてもよい
});
```

`userAgent`は、決済後に戻るブラウザを指定するための値です。仕様書の対応範囲はAndroidとiOSのChrome・Firefox・UC Browser・Yahoo Browserで、シークレットモードやプライベートブラウズでは正しく戻れません。戻れなかった顧客の注文も取りこぼさないよう、次のステータス確認を戻り先ページとは別の経路で動かします。

`merchantPaymentId`の再利用は注意が必要な操作です。仕様書には、同じ値で再リクエストすると前回の結果が返るという記載と、重複を示す`DUPLICATE_DYNAMIC_QR_REQUEST`の両方があります。どちらの場合も新しいコードは作られないため、期限切れ後に決済をやり直す場合は、注文に紐づく新しい`merchantPaymentId`を発番します。

### 決済詳細取得APIのポーリング間隔とステータス7種別の分岐処理

支払い結果は`GET /v2/codes/payments/{merchantPaymentId}`で取得します。ウェブペイメントの仕様書は、照会する場合の間隔を2〜3秒程度としています。ステータスは`CREATED`・`AUTHORIZED`・`COMPLETED`・`EXPIRED`・`CANCELED`・`FAILED`・`REFUNDED`の7種です。

```
async function checkPayPayStatus(merchantPaymentId) {
  const response = await PAYPAY.GetCodePaymentDetails([merchantPaymentId]);
  const { status, paymentId } = response.BODY.data;
  switch (status) {
    case 'COMPLETED':
      await markOrderPaid(merchantPaymentId, paymentId); // 返金で使う paymentId を保存
      return 'paid';
    case 'CREATED':
      return 'waiting'; // まだ支払われていない。2〜3秒後に再照会
    case 'EXPIRED':
    case 'FAILED':
    case 'CANCELED':
      return 'retry'; // 新しい merchantPaymentId で決済をやり直す
    default:
      return 'check'; // AUTHORIZED と REFUNDED は担当者が確認する
  }
}
```

ここで`paymentId`を保存しておく点が後で効きます。返金APIと与信取消APIは、加盟店側の`merchantPaymentId`ではなく、PayPayが発番した`paymentId`を求めるためです。ポーリングは顧客が画面を開いている間だけにとどめ、閉じた後の確定は次章のWebhookに任せます。

## SDKを使わずHMAC認証でOPAを直接呼び出すリクエストの組み立て方

SDKの保守が限定的なこと、Node.js以外の言語やサーバーレス環境で依存を減らしたいことから、APIを直接呼ぶ実装も選択肢になります。その場合はHMAC認証を自前で組みます。

### Authorizationヘッダを構成する6要素と署名対象文字列の順序

[PayPay公式のHMAC認証の仕様書](https://www.paypay.ne.jp/opa/doc/jp/v1.0/api%5Fauthorization)によると、Authorizationヘッダは`hmac OPA-Auth:{API Key}:{macData}:{nonce}:{epoch}:{hash}`の形式です。手順は3段階です。

1. Content-Typeとリクエストボディを順にMD5へ入れ、結果をBase64にしてhashとする（ボディが無ければhashとContent-Typeを`empty`にする）
2. パスのみのURL・HTTPメソッド・nonce・epoch・Content-Type・hashを、この順に改行で連結する
3. 連結した文字列をAPIキーシークレットでHMAC-SHA256し、Base64にしてmacDataとする

nonceは長さ8の任意の文字列が推奨で、epochは秒単位のUNIX時刻です。サーバー時刻とのずれは2分未満でなければなりません。コンテナやサーバーレスでは時刻同期が効いていないと認証が通らないため、NTPの状態も確認対象に入れます。

### Node.js標準のcryptoでmacDataを計算しQRコードを作る実装例

外部パッケージを使わず、Node.js 18以降の標準の`crypto`と`fetch`だけで書くと次のようになります。

```
const crypto = require('crypto');

const BASE = 'https://apigw.sandbox.paypay.ne.jp'; // 本番は https://apigw.paypay.ne.jp
const { PAYPAY_API_KEY, PAYPAY_API_SECRET, PAYPAY_MERCHANT_ID } = process.env;

function buildAuth(method, path, body) {
  const nonce = crypto.randomBytes(4).toString('hex'); // 8文字
  const epoch = Math.floor(Date.now() / 1000);
  let contentType = 'empty';
  let hash = 'empty';
  if (body) {
    contentType = 'application/json;charset=UTF-8;';
    hash = crypto.createHash('md5').update(contentType).update(body).digest('base64');
  }
  const signed = [path, method, nonce, epoch, contentType, hash].join('\n');
  const macData = crypto.createHmac('sha256', PAYPAY_API_SECRET).update(signed).digest('base64');
  return {
    authorization: `hmac OPA-Auth:${PAYPAY_API_KEY}:${macData}:${nonce}:${epoch}:${hash}`,
    contentType,
  };
}

async function createCode(order) {
  const path = '/v2/codes';
  const body = JSON.stringify({
    merchantPaymentId: order.paymentId,
    amount: { amount: order.total, currency: 'JPY' },
    codeType: 'ORDER_QR',
    redirectUrl: `https://example.com/orders/${order.id}/complete`,
    redirectType: 'WEB_LINK',
  });
  const { authorization, contentType } = buildAuth('POST', path, body);
  const res = await fetch(BASE + path, {
    method: 'POST',
    headers: {
      Authorization: authorization,
      'Content-Type': contentType,
      'X-ASSUME-MERCHANT': PAYPAY_MERCHANT_ID, // 加盟店IDの指定が必要な構成のとき
    },
    body,
  });
  return res.json(); // resultInfo.code と data.url を確認する
}
```

署名に使うボディと送信するボディは、同じ文字列でなければなりません。`JSON.stringify`を2回呼ぶと、キーの順序や空白が変わった時点でhashが一致しなくなります。署名対象のパスにクエリ文字列やホスト名を含めないことも、仕様書の例どおりに守ります。加盟店識別子はクエリの`assumeMerchant`でも渡せ、両方を指定した場合に優先されるのはクエリです。

## Webhook・キャンセル・返金で決済後の注文状態を正しく保つ実装

決済コードの作成までは数十行で書けます。手間がかかるのは、顧客が戻ってこない場合と、決済後に取り消す場合の処理です。

### Transaction通知の受信と決済詳細APIで状態を再確認する流れ

Webhookでは、取引の状態が変わるたびに`notification_type`が`Transaction`の通知がPOSTで届きます。届く`state`は`AUTHORIZED`・`COMPLETED`・`CANCELED`・`EXPIRED`・`EXPIRED_USER_CONFIRMATION`・`FAILED`で、ペイロードには`merchant_order_id`や`order_amount`が入ります。処理成功時に推奨される応答は`200 OK`です。

仕様書は送信元IPアドレスのホワイトリスト登録を強く推奨しています。受け取った通知はそのまま信じず、`merchant_order_id`で決済詳細取得APIを呼び直し、`COMPLETED`と金額の一致を確かめてから注文を確定させる構成にします。同じ通知が2回届いても注文を二重に作らないよう、`merchantPaymentId`を一意キーにして確定処理を1回に絞る構成です。冪等な確定処理の書き方は[決済Webhookの署名検証と冪等な注文確定](https://www.issoh.co.jp/tech/details/15734/)で解説しています。

日次の突合ファイルも同じWebhookの`file.created`で届き、通知は毎日1時30分から10時（日本時間）の間です。会計システムとの照合をバッチで組むなら、この時間帯を前提に処理時刻を決めます。

### 翌日0時20分までのキャンセルと期限後に使う返金APIの使い分け

決済の取り消しは、時期によって使うAPIが変わります。キャンセルは`DELETE /v2/payments/{merchantPaymentId}`で、受付時に202を返す非同期処理です。動的ユーザスキャンの仕様書では、与信を使わない決済のキャンセル期限は決済発生翌日の0時20分（日本時間）とされています。

| 状況             | 使うAPI                     | 指定するID              |
| -------------- | ------------------------- | ------------------- |
| 支払い前のコードを無効にする | DELETE /v2/codes/{codeId} | codeId              |
| 決済翌日0時20分まで    | 決済キャンセルAPI                | merchantPaymentId   |
| それ以降の取り消し      | POST /v2/refunds          | paymentId（PayPay発番） |

返金で合わせて指定するのは、加盟店が発番する`merchantRefundId`です。返金APIは受付だけを行い、結果は`GET /v2/refunds/{merchantRefundId}`で確認します。返金できる期間を過ぎると`REFUND_WINDOW_EXCEED`が返り、PayPay商品券の有効期限切れも理由になりえます。Node.js SDKのREADMEには、返金は現時点で1注文につき1回のみ対応という記載です。一部返金を2回に分ける運用は組めない前提で、管理画面の返金ボタンを設計します。

### 通販の出荷売上で与信と売上確定を分ける追加APIと加盟店の利用条件

受注時に残高を押さえ、出荷時に売上を確定したい通販では、[出荷売上（PreAuth & Capture）の仕様書](https://www.paypay.ne.jp/opa/doc/jp/v1.0/preauth%5Fcapture)に記載されたAPIが選択肢です。コード作成時に`isAuthorization`を`true`にし、出荷時に`POST /v2/payments/capture`へ`merchantCaptureId`と金額を送ります。欠品時は`POST /v2/payments/preauthorize/revert`で与信を取り消し、ここでも`paymentId`を指定します。

この機能は加盟店ごとに対応可否があり、非対応の加盟店では`PRE_AUTH_CAPTURE_UNSUPPORTED_MERCHANT`が返ります。設計に組み込む前に、契約で使えるかをPayPayに確認します。与信と売上確定を分ける考え方そのものは[オーソリと売上確定の実装パターン](https://www.issoh.co.jp/tech/details/15420/)を参照してください。

### RATE\_LIMITやMAINTENANCE\_MODEなどエラーコード別の扱い方

全APIに共通するエラーのうち、実装で分岐させるものは次の5つです。

- `UNAUTHORIZED`（401）：APIキーとシークレットが無効。環境とキーの組み合わせを疑う
- `RATE_LIMIT`（429）：流量制限に達した。間隔を空けて再試行する
- `MAINTENANCE_MODE`（503）：メンテナンス中。PayPayを選択肢から一時的に外す
- `DYNAMIC_QR_PAYMENT_NOT_FOUND`（400）：コードが無効化されたか該当なし。新しいコードを作る
- `SERVICE_ERROR`・`INTERNAL_SERVER_ERROR`（500）：PayPay側の問題。決済詳細を照会してから再試行を判断する

500系で再試行するときは、先に決済詳細取得APIで状態を見ます。決済は成立していたのに応答だけ失敗した場合に、二重に請求しないためです。

## PayPay APIを直接契約で組むか決済代行経由にするかの判断基準

PayPayを受け付ける経路は、直接契約のOPA、Stripe経由、PAY.JP経由などがあります。どれを選ぶかは、既存の決済基盤で決まる部分が大きいです。

### PayPayと直接契約してOPAを実装する価値がある事業の条件

直接契約のOPAを選ぶのは、次のいずれかに当てはまる場合です。PayPayの入金と手数料を決済代行を挟まずに管理したい、出荷売上で受注時の与信と出荷時の確定を分けたい、自社アプリからPayPayアプリを呼び出す決済を組みたい、のいずれかです。

逆に、PayPayだけのために専用の認証・ステータス管理・Webhook・返金画面を作ることになる点は、見積もりで軽く扱わないでください。カード決済と別の管理画面、別の入金サイクル、別の突合ファイルを運用する体制が要ります。決済手段がPayPayだけ、あるいはPayPayが売上の大半を占める事業でなければ、この運用負担は割に合いません。

### Stripe・PAY.JP経由にしてPayPay APIの直接実装を見送る場面

すでにStripeでカード決済を動かしているなら、PayPayの直接実装は見送り、Stripeの決済手段に追加します。[Stripe経由のPayPay決済の実装手順](https://www.issoh.co.jp/tech/details/18529/)が手順と制約の参照先です。ただしStripe経由は継続課金・Connect・手動キャプチャーに非対応なので、出荷売上が必要ならこの記事のOPAに戻ります。PAY.JPを使っている場合は、PayPayがAPI v2経由でのみ提供されるため、[PAY.JPのAPI v1・v2の違い](https://www.issoh.co.jp/tech/details/15722/)を先に確認します。

判断に迷うのは、カードとPayPayの売上比率がまだ読めない新規サービスです。この場合は決済代行経由で始め、PayPayの比率が高いと分かってから直接契約へ移す順番が手戻りの少ない進め方です。決済手段の構成、在庫引当や返金を含む決済フローの設計、既存システムへのPayPay追加を外部に任せたい場合は、[決済・サブスクリプションシステム開発](https://www.issoh.co.jp/service/system/payment/)で要件の整理から相談できます。

## PayPay APIの実装とPayPay for Developersに関するよくある質問

PayPay APIを使った決済の実装でよく出る疑問をまとめました。

### PayPay APIは個人や加盟店登録前でも使えますか？

サンドボックスでの開発と動作確認は、PayPay for Developersのアカウントを作れば始められます。本番でPayPay決済を受け付けるには、公式の仕様書が定めるとおりPayPayの加盟店登録が必要で、審査を経て本番用のAPIキーとシークレットが発行されます。個人で開発する場合も、実際に代金を受け取るための前提は加盟店としての契約です。

### PayPay APIの利用料や手数料はいくらかかりますか？

APIの呼び出し自体に料金がかかるという記載は、2026年11月時点の仕様書にはありません。費用は加盟店としての決済手数料で、料率は契約形態やプランで変わります。オンライン決済の料率は申込時の条件で確認してください。店舗向けプランの料率の見方は、関連記事のPayPay申込・審査の解説で扱っています。

### PayPayのQRコードの有効期限はどれくらいですか？

決済コードの有効期限は、作成時のレスポンスの`expiryDate`に入ります。固定の分数を前提にせず、画面のカウントダウンや再作成の判定に使うのは、このレスポンスの値です。期限が切れたコードは`EXPIRED`になり、照会では`DYNAMIC_QR_PAYMENT_NOT_FOUND`が返ることがあるため、新しい`merchantPaymentId`でコードを作り直します。

### PythonやPHPでもPayPay APIを実装できますか？

PythonやPHPでも実装は可能です。公式SDKはNode.jsのほか、Python・PHP・JavaがGitHubで公開されています。ただしNode.js SDKのREADMEは保守が限定的だと注記しており、新しいAPIの反映先は、SDKよりも仕様書が先です。SDKに無い機能を使うときは、この記事のHMAC認証の手順で直接呼び出す実装に切り替えます。

### Webhookが届かないときは何を確認すればよいですか？

まずTest ModeとLive Modeのどちらの通知先が登録されているかを確認します。ヘルプセンターの案内では、本番のWebhook設定は加盟店側の画面では変えられず、問い合わせフォームで変更を依頼する方式です。受信側のファイアウォールでPayPayの送信元IPを許可しているかも確認し、届かない間は決済詳細取得APIの照会で注文を確定できるようにしておきます。

## 関連記事

- [Stripe PayPay決済の実装手順：有効化・Checkout・PaymentIntentのコードと使えない機能](https://www.issoh.co.jp/tech/details/18529/)：PayPayを直接契約せずStripe経由で受け付ける実装と制約。
- [QRコード決済の導入手順｜PayPayの申込・審査・入金設定と手数料、まとめ導入の判断](https://www.issoh.co.jp/column/details/18877/)：OPAの前提となる加盟店申込と審査、手数料の見方。
- [決済Webhookとは？仕組み・主要イベントと署名検証・冪等な注文確定の実装を開発視点で解説](https://www.issoh.co.jp/tech/details/15734/)：PayPayの通知で注文を確定する処理の作り方。
- [PAY.JPとは？手数料3プランとAPI v1・v2の違い、実装コードとStripeとの選び分け【2026年10月】](https://www.issoh.co.jp/tech/details/15722/)：PAY.JP経由でPayPayを受け付ける場合の比較先。
- [QRコード決済のCPMとMPMの違い｜仕組み・端末とPOSレジ連携、店舗の導入形態と手数料](https://www.issoh.co.jp/column/details/18120/)：店舗レジでのQRコード決済とオンライン決済の違い。

---

出典: [PayPay APIの実装手順：OPAのサンドボックス・QRコード決済・HMAC認証をNode.jsで解説](<https://www.issoh.co.jp/tech/details/19875/>)（株式会社一創）
