PayPal開発の備忘録(REST APIや運用の際の注意点など)
概要
最終更新:22/05/18
ネットで検索すると見つかるQiitaの記事は入り口としてはとても有用なので活用したい。
(PayPalの公式ドキュメントからもQiitaへのリンクがある)
https://qiita.com/PPJP/items/13fa67cbb9dce57b701b
ここでは開発を通して知識になったことをまとめます。
事前にやるべきこと
以下の事をしっかり行っていないと運用開始してある程度するとPayPalから通知が来てPayPalの機能を止められる可能性があります。
最初は一部機能…送金など…が止められて期限内に対応しないとPayPalのほぼすべての機能が止まるみたいです。
事業情報をPayPalにしっかりと提出する
おそらくお問い合わせやメッセージでPayPalにコンタクトを取って事前にPayPal支払いを行うサイトの詳細調査を依頼するべきです。
サイトの規模やどのような支払いをするのかという事をPayPal側に聞かれると思いますので1つ1つ答えてください。
結構いろいろ聞かれます、情報取扱責任者の工数は少し取られるかと思います
サイトの規模にもよると思いますがだいたい1ヶ月程度を見積もっておけば安心です。
留意しておく点
致命的なものが無い限りは問題は無いと思いますが、留意しておくと良いです。
想定顧客の国
制限対象国というのがいくつかあります(北朝鮮、イラン、キューバ…など)
会員登録する時の本人確認の有無
本人確認を行っている?行っている場合はどんな情報を取っている?プロセスは?
アンチマネーロンダリングのモニタニングの有無
どのように不正取引を防止している?
PayPal以外の決済とPayPal決済の比率
要はPayPal以外の精算方法として何を導入予定/導入しているか
買い手保護、売り手保護
PayPalには取引の保護をする制度があります。
これらの保護の適用には条件があります。適用条件はどちらも確認しておくべきです。
- その条件を満たしているか?
- 満たしておかないとリスクがあるか?
特に「配送証明」は重要です。各取引も詳細まで(取引日期、買い手情報、売り手情報、商品名、商品詳細、単価、数量…など)ログとして保存しいつでも取引と参照できるようにシステムを用意しておくべきでしょう。
買い手保護
例えば「商品を購入したのに届かない」などトラブルが発生したときに売り手に対して返金を要求できます。
売り手保護
例えば「(本当は商品をPayPal経由で買ってないのに)商品が届いていない」などのクレームに対して保護してくれたり「クレジットカード所有者からのカード会社へのチャージバック」などのトラブルから保護してくれます。
開発の流れ
サンドボックス環境と開発者サイトを利用して開発を進めます。開発者サイトでサンドボックス環境にアカウントを作ったり、ログを確認することができます。
サンドボックス環境では開発者サイトで作成したアカウントでしかログインすることができないので、普段PayPalで使っているアカウントではログインできない点に注意。
サンドボックス環境
PayPal本番環境と同等な環境の事です。ここでは開発者サイトで作成したアカウントでしかログインできません。
https://www.sandbox.paypal.com/
開発者サイト
例えばREST APIを使うためのAppsの作成。APIログの確認。サンドボックス用のアカウントの作成。ドキュメントの確認…などPayPalで開発をすることになったらお世話になるサイトの事。
ここのログインにはPayPal本番環境の情報を使います。
※ 結構動作が怪しいのでちょくちょくエラーになります。下手するとドキュメントも開けなくなる。
ビジネスアカウントの場合でユーザーの管理をする
ビジネスアカウントの場合PayPal本番環境で普段使っているアカウントで開発者サイトのログインをすることは非推奨。
PayPalの機能としてビジネスアカウントにユーザーを追加して権限の割当を行うことができるので必要な権限を持ったユーザーを作ってそのユーザーでログインして操作する事を推奨します。(操作ミスを防ぐため過度な権限を割り当てているアカウントを極力使わない)
自分以外のユーザーが私のpaypalビジネスアカウントにアクセスし管理することを承認できますか。
サンドボックス用アカウントの作成
売り手と買い手2つのアカウントタイプがあります。
売り手(Business)
商品を販売する側のアカウント。主にAppsを作るときに紐付けられる。
なお、売り手が販売している商品を自分で買うことはできないので後述する買い手アカウントを作成してこちらを使って購入する必要があります。
※ AppsはREST APIなどに設定するClient IDとSecretを生成する
買い手(Personal)
商品を買う側のアカウント。
異常系のテスト方法
売り手のアカウントでエラーの検証をONにする必要があります。ONにしないとエラーが帰ってくるリクエストを飛ばしてもエラーが帰ってきません。
Account→売り手アカウントの詳細を開く→Settings→Negative TestingをONにする。
REST APIの異常系のテスト方法
ヘッダに特定のJSONをつけるだけです。
https://developer.paypal.com/docs/api-basics/sandbox/request-headers/
PayPal-Mock-Response: {"mock_application_codes": "DUPLICATE_INVOICE_ID"}
DUPLICATE_INVOICE_IDの部分はAPI毎に変わります随時確認してください。
- https://developer.paypal.com/docs/api/payments/v2/#errors
- https://developer.paypal.com/docs/api/orders/v2/#errors
※ NVP/SOAP APIsという呼び出し方法もありますがレガシーなので使う理由は特にないと思います。
手数料について
決済手数料は基本的に最終的に引かれた額のみ知る事ができます。PayPalアカウントの取引履歴から個別に確認できます。
手数料率は変動する手数料率 + 固定手数料になるので事前にいくらかかるか計算するのが難しいです。
よって「手数料を事前に知るのは諦める事」を仕様に抑えるべきでしょう。
小数点以下は四捨五入されます(日本円の場合)
補足情報
ここからは手数料率を細かく知りたい人向けです。
変動とはいえ大まかには決まっている。基本は以下から確認してください。
ここから月の売上や国により手数料率が変動する。
- https://www.paypal.com/jp/webapps/mpp/lp/partner
- https://www.paypal.com/jp/webapps/mpp/merchant-fees
scriptタグ読み込み(SDK読み込み)
プラグインとかもあるので結構柔軟に呼び出せる。
https://developer.paypal.com/docs/business/javascript-sdk/js-sdk-performance/
決済時にユーザーからの住所情報を受け取らない
デジタルコンテンツを販売する場合などは住所が不要な場合もある。
create/orders の場合はリクエストに以下を追加してあげると住所不要になる。
application_context: { shipping_preference: 'NO_SHIPPING' }
細かい設定はドキュメントを参照。このようにリクエストで条件をコントロールできるので確認しておくことをおすすめします。
決済完了しているが保留ステータス
PayPalを利用し始めたとかで信用が低い場合や、一部の通貨取引は決済自体は通したけれども、その決済は売り手側で保留中という状態になってしまうことがあるみたいです。
この状態になるとPayPal管理画面の取引はまだ売上確定していない状態になるので、該当する取引を確認し手動で「売上を受け取る」ボタンを押す必要があるようです。
テストする場合は開発者サイトから
Account→売り手アカウントの詳細を開く→Settings→Payment reviewをONにして決済をすると再現可能です。
- PayPal payment status 'PENDING' after order capture 'COMPLETED' (reason: unilateral) - Stack Overflow
- paypalの支払いが保留されているのはなぜですか。
REST APIのレスポンス
保留にならずに終わった取引のレスポンスと、上記のように保留になった取引のレスポンスは一部パラメーターに欠損がある。
例えば以下のパラメーターは保留の取引の場合に存在しない。パラメーターの存在に依存したシステム設計だとエラーになる可能性があるので注意。
よく発生するエラー
運用をすると以下のエラーが目立つので事前に動作チェックができるといいかもしれません。
PayPalでは支払いが完了しているがサイトに支払い状態が反映されない
これは稀に発生します。PayPalから支払い完了という通知を受け取るときにネットワークが途切れてしまったり、ユーザーの通信環境など様々な要因で発生するみたいです。
なのでPayPal側で支払いは完了しているが、サイトに支払い状態が反省されない可能性があることを十分に考慮して設計をするべきです。
ユーザーに不便をかけてしまいますが返金という方法を取るのが一番確実だと思います。
一応APIを使うことでキャンセル(返金)を行うことはできるのですがお金が絡む問題なのでそこはポリシー次第かなと言った感じです。
PayPal送金を利用してユーザーに送金する必要がある場合
【重要】
まず凄く重要な点として以下の案内は必ず確認しましょう。
要は100万を超える額が口座にある場合、それを送金に使うのかどうかの案内がPayPalから送られてくるはずなので確実に対応しましょう。
対応が漏れると例外なく銀行口座へ引き落とされユーザーに送金する場合はクレジットカードを利用する事になります
送金のリスクを把握する
日本のPayPalでは海外ではできるが日本ではできない機能があるみたいです。
例えば
よって送金は「クレジットカードを利用する」または「PayPal支払いをサイトに実装し振り込まれた売上から送金する」の2択の仕様になります。
なのでクレジットカードが止まり送金ができなくなってしまうというリスクが発生します。
一括送金について
一括送金はPayPalにお問い合わせをして機能を開放してもらう機能なのですが
どうやら2022年5月18日現在、新規での提供をしていないようです。(お問い合わせにて確認)
モデルケース
BtoCtoCのようなビジネスモデルを運用している場合で
(プラットフォームを企業が提供し、ユーザー間で商品を売買、売上から手数料を企業側が取り、残りをユーザーへ送金する)
支払い方法に
- クレジットカード
- 銀行振込
- PayPal
などを実装している場合で、売上の送金方法にPayPal口座が存在する場合は注意して実装する必要があります。
この場合、前述の通りPayPalは事前に手数料を予想することが困難です、なので手数料が高い条件のユーザーがPayPal支払いを多く行い手数料が取られてしまった場合
「ユーザーの送金申請額 > PayPal口座残高」という事が発生してしまう可能性があり
この場合は「クレジットカードを利用しての送金」が発生してしまいクレジットカードが止まるなどのリスクを背負うことになります。
蛇足(対策案)
PayPal以外の取引がある時点でプラットフォームではPayPalでの売上とそれ以外で口座を分けておくと後々対応がしやすくなると思います。
リスクを回避する為には「PayPalでの売上分しかPayPalに送金できない」というルールを周知する必要があります。
なのでプラットフォームでは、PayPal取引の場合は手数料率を変更するなどリスク回避のための施策を検討して「PayPal口座残高 > プラットフォーム全体で送金可能なPayPal口座残高」になるようにしたいところです。
まぁこのあたりは他の決済代行会社にも言えることですけれどね…
お問い合わせ方法
電話でのお問い合わせとメッセージでのお問い合わせの2パターンがあります。どちらも日本語で大丈夫です。
数回電話でお問い合わせをしましたが日本語での疎通に全く問題のない外国の方に対応していただきました。びっくりするぐらい流暢だったので電話でのサポートは安心してもいいと思います。