ネイティブペイメント (1.1)

PayPay オープン決済API（OPA）は、PayPayの決済パートナーが、エンドユーザーに対して快適な決済体験を提供できるよう、 様々なシナリオでの決済関連の操作が設計されています。

PayPay OPAクライアントとして登録されている場合、決済パートナーは下記の機能が使用可能になります。

• PayPayユーザーのウォレットから直接支払い金額を引き落とし、決済を回収する
• スムーズな決済を行うために事前認可を使用して、決済フローを取得する
• 決済を回収するためのPayPayキャッシャーページとWebアプリケーションの統合
• PayPay OPAが提供する豊富なAPIを使用して、精算のエクスペリエンスの構築

本書では、PayPay決済パートナー向けに設計したAPIに焦点を当てます。

PayPay Open Payment APIでは、セキュリティ対策としてTLS 1.2以上の使用が必須となっております。TLS1.0およびTLS1.1では接続できませんのでご注意ください。

PayPay OPAの利用を開始するには、事前に定義されたプロセスに従って、PayPay加盟店として登録をしなければなりません。 このプロセスは 情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。 このプロセスが完了すると、加盟店はPayPayプラットフォームに登録され、 QRコードスキャンとPOS統合によってPayPayユーザーからオフラインでの決済を回収する準備が整います。

オンライン決済統合の場合、加盟店用にOPAクライアントが作成され、以下の項目が設定されます。

• api keyとsecret
• 許可された認可コールバックドメイン
• ユーザー認可有効期間
• Webhookエンドポイント
• クライアントIPホワイトリスト

これらの設定を管理するには、マーチャントパネルを使用するか、弊社営業担当までご連絡ください。

ユーザーからのPayPayアプリ、PayPayWeb画面への日本国外からのアクセスは制限されています。詳細については個別にご相談ください。

PayPayユーザーのウォレットから決済を回収できるようにするには、ユーザーの認可を明示的に取得する必要があります。

ユーザー認可を取得する方法については、 こちら をご参照ください。

また、SCOPEには"direct_debit"を指定して下さい。Get user wallet balanceを使用する場合のみ、"direct_debit,get_balance"を指定して下さい。

OPA API認証に関わることは全て API認証のページ にあります。

APIのリクエスト時に加盟店識別子をセットする必要があります。 加盟店識別子をセットするには2つの方法があります。

クエリの中にセットする:

?assumeMerchant={MerchantId}

HTTPヘッダにセットする:

X-ASSUME-MERCHANT: {MerchantId}

両方を指定した場合、クエリにセットしたパラメーターが優先されます。

PayPay OPAはhttpレスポンスステータスコードとOPAエラーコードを使用してリクエストの成功または失敗を示します。 これらの情報を使用して、どのようなエラー対応をするかを判断できます。 通常、PayPay OPAは以下のhttpレスポンスステータスコードを返します。

各API共通レスポンスコード

Create a payment

以下のエラーはユーザーがKYC（本人確認）を完了していない場合に発生します。

以下のエラーは使用した支払い方法がCREDIT_CARDまたはPAY_LATER_CCの場合に発生します。

Get payment details

Cancel a payment

Refund a payment

Get refund details

Create a topup QR Code

Get topup status

Delete QR code

Unlink user

Get user authorization status

Get masked user profile

Check user wallet balance

Expected cashback

Get payment methods

推奨タイムアウト値は各APIで指定されています。 決済APIのタイムアウト値は30秒未満であってはいけません。 タイムアウトが発生した場合、それは状態が不明な決済として扱ってください。

この状況に対処する方法は2つあります。

1. 取引の状況を照会するには、照会APIを使用してください。PayPayにおいて元の取引が失敗になっているか存在しない場合は、同じ取引として新しいトランザクションを開始できます。

2. キャンセルAPIが提供されている場合は、取引をキャンセルすることもできます。キャンセルが承認された後、同じ取引として新しいトランザクションを開始できます。

OPAに関するその他のFAQについては こちら をご覧ください。

ユーザー認可のステータス変更に伴い、APIの実行に失敗する場合があります。 想定されるユーザー状態と、対応するAPI実行結果は下記の通りとなります。他APIにおいて、ステータス変更に伴うエラーは発生しません。

Get user authorization status

Create a payment、Get payment methods、Get Sets of Cashback Information、Create topup QR code、Get user wallet balance、Check user wallet balance、Get masked user profile

Refund a payment

決済・取消に関して

ユーザーのウォレット残高に関して

ユーザー管理に関して

ユーザーがPayPayアプリからの通知を許可している場合、以下の内容の通知がユーザーへ配信されます。

Push通知

イベント毎の基本的なステータスの遷移と、WEBHOOK通知については下記の通りとなります。

PayPayは、アカウントでイベントが発生したときにアプリケーションに通知するWebhookを送信します。 通知を受信するためには、POSTメソッドを使用してクライアントにデータを送信するWebhook URLを設定する必要があります。 すべての通知データには、どのイベントが発生したかを判断するためにクライアントサービスで使用できるnotification_typeフィールドがあります。

Webhook処理が正常に終了した場合、200 OK のHTTPステータスコードを返してください。 レスポンスボディは必須ではないですが、"OK"など、簡単な文字列を返していただくことを推奨します。

セキュリティ上の問題から、通知受信において、クライアントによるPayPay IPアドレスのホワイトリスト登録を強く推奨します。

現在Webhookに送信されている通知について、以下もご一読ください。

ユーザー状態の変化に関連するイベントです。 authroization の部分は文字通りです。

通知の種別ごとの例は以下の通りです。

この通知は、クライアントがユーザーの認可を正常に取得した場合に送信されます。

{
  "notification_type": "customer.authroization.succeeded",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "scopes": "direct_debit",
  "userAuthorizationId": "xxxxx",
  "profileIdentifier": "*******5678",
  "expiry": 1234567  // the authorization id expiration epoch timestamp in seconds
}

この通知は、クライアントがユーザーの認可の取得に失敗した場合に送信されます。

{
  "notification_type": "customer.authroization.failed",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "result": "declined",  // or bad_request
  "reason": "invalid scope"
}

Payloadのresult（結果）は、リクエストがユーザーによって拒否された場合はdeclined（拒否された）、 リクエストに無効な情報がある場合はbad_request（不正な要求）のいずれかになります。

この通知は、ユーザーがPayPayアプリから、認可を取り消した場合に送信されます。

{
  "notification_type": "customer.authroization.revoked",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "userAuthorizationId": "xxxxx",
  "referenceId": "yyyy"
}

この通知は、ユーザー認可の期限がPayPayによって延長された場合に送信されます。

支払いの実施／認可の取得をした場合にユーザー認可の期限を延長します。 これにより、ユーザー操作による認可の取得を減らすことができるため、ユーザーへの負担を減らすことができます。

{
    "notification_type": "customer.authroization.extended",
    "notification_id": "evt_aXnbdeFt2Ke",
    "createdAt": "1349654313",
    "scopes": "direct_debit",
    "userAuthorizationId": "xxxxx",
    "expiry": 1234567  // 秒単位の認証ID有効期限エポックタイムスタンプ
}

この通知は、ユーザーが退会した時に送信されます。

サンプル・イベント:

{
  "notification_type": "customer.authroization.canceled",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "userAuthorizationId": "xxxxx"
}

PayPayでは取引明細ファイル（突合ファイル）を日次の処理で生成し、Webhookで通知します。

Sampleファイルをダウンロード

Webhookで通知されたpathからファイルを取得してください。

{
  "notification_type":"file.created",
  "notification_id": "<UUID>",
  "fileType":"transaction_recon",
  "path":"https://<server_path>/<filename>?parameters",
  "requestedAt":"<epoch time>"
}

最新のFAQについてはこちらをご参照ください。