PayPal 支付接口詳解

PayPal 支付接口詳解

PayPal 快速、安全而又方便，是跨國交易的首選在線付款方式。現在PayPal可以和國內大部分信用卡關聯,可以實現國人的跨國交易收支。

申請PayPal註冊網址： https://www.paypal.com/

paypal接口與其它接口有些不同，稍微復雜一點。 其實銀行接口也算是一個站點的插件。

所謂paypal ipn（Instant Payment Notification），就是Paypal開發的一種能主動通知第三方賣家系統交易狀態的一種機制。IPN的原理很簡單，就是當產生了一個交易之後， 交易狀態發生變化時，如用戶已經付款、或者退款、撤銷時，Paypal利用常用的HTTP POST方式，將交易的一些變量提交給網站的某個頁面（稱之為IPN Handler），當這個頁面接受到請求時候，將這些數據原封不動加上一個指示驗證的cmd=_notify-validate，POST回Paypal 的接口地址，如果數據正確，那麽Paypal返回字符串VERIFIED，否則為INVALID，如果結果為VERIFIED，那麽你的程序就可以使用這 些數據進行操作。

開設Sandbox帳號

但代碼的調試是一件很痛苦的事情，因為作為第三方開發人員，不可能開兩個帳號，每次測試還要 之間交易一些錢，所以Paypal專門開發了Sandbox給開發人員進行開發，首先到 https://developer.paypal.com/ 註冊一個開發帳號，好了之後再進入Sandbox建立測試用的Paypal虛擬帳號（至少應該建立一個Business的和一個Personal的），這 種賬號註冊方法和Paypal的流程一樣，信息可以是假的，包括銀行帳號、信用卡（其實Paypal Sandbox會自動生成一些隨機的號碼）。接下來需要激活Paypal Sandbox的虛擬帳號，註意，這裏不管你在Paypal Sanbox註冊時填什麽郵件地址，有任何發送到虛擬帳號所填郵箱的郵件都存會在開發帳號的管理界面中的Email頁（導航欄上有）中。登錄 Sandbox的虛擬Paypal環境，還需要驗證虛擬帳號的銀行，這裏可以隨便填，然後通過Add Funds來給賬戶充值（想填多少填多少 920-203 920-533 ）。然後，還需要激活IPN的選項，在Business的那個賬戶的Profile設置頁面中，點擊，然後點擊Edit按鈕，打開IPN，這裏如果你使用的是固定的IPN Handle，可以直接將地址填入。

接下來，我們測試的時候，應該將Paypal接口的地址設置為  https://www.sandbox.paypal.com/cgi-bin/webscr

基本的流程

當客戶向您付款時，PayPal將向位於指定 URL (type=”hidden” name=”notify_url” value=” “)的服務器發送一個通知。此通知中將包括您的客戶的所有付款信息（例如，客戶名稱、金額），以及一段加密代碼。當服務器收到通知時，它隨後會將該信息 （包括加密代碼）發送回安全的PayPal URL。PayPal將通過檢查加密字符串對交易進行身份驗證。這種將 IPN 數據傳回PayPal的操作防止了“欺騙”，因此您可以確保 IPN 來自PayPal。在進行驗證時，PayPal會將其合法性的確認信息發送回您的服務器。

提示：要啟用即時付款通知，您將需要輸入一個 URL，通過它您可以接收到來自您的用戶信息的通知。

啟用了即時付款通知後，每次當您接收付款時您的服務器都會收到一個通知，此通知將以隱藏的“FORM POST”的方式發送到指定的 URL，並將包括所有付款信息。此頁面的底部列出了通知的 FORM 變量。

每次收到來自PayPal的 IPN 時，您必須在實施訂單之前完成如下所述的通知確認過程。確認列出的信息將可確保交易合法。

通知確認IPN

為了確保付款已進入您的PayPal賬戶，您必須驗證用作“receiver_email”的電子郵件地址是否已在您的PayPal賬戶中註冊並得到確認。

服務器收到即時付款通知後，您將需要通過構建一個發送到PayPal的 HTTP POST 對其進行確認。您的 POST 應發送到 https://www.paypal.com/cgi-bin/webscr

您必須完全按照收到表單變量時的原樣發送所有收到的表單變量。您還需要將一個值為“_notify-validate”的名為“cmd”變量（例如，cmd=_notify-validate）附加到 POST 字符串。

PayPal將回復該 POST，並在回復的正文中包含一個單詞“VERIFIED”或“INVALID”。當您收到 VERIFIED 回復時，您需要在實施訂單之前執行若幹檢查：

• 確認“payment_status”為“Completed”，因為系統也會為其他結果（如“Pending”或“Failed”）發送 IPN。
• 檢查“txn_id”是否未重復，以防止欺詐者重復使用舊的已完成的交易。
• 驗證“receiver_email”是已在您的PayPal賬戶中註冊的電子郵件地址，以防止將付款發送到欺詐者的賬戶 。
• 檢查其他交易詳情（如物品號和價格），以確認價格未改變完成了以上檢查後，您可以使用 IPN 數據更新您的數據庫，並處理購物。

 

如果收到“無效”通知，則應將其視為可疑通知，並應對其進行調查。

主要參數：

向PayPal提交粘貼代碼時，應包括以下 4 個隱藏變量及一張圖片，這就是說，您粘貼到PayPal的最短必需代碼應如下：

 

ion="        https://www.paypal.com/row/cgi-bin/webscr" method="post">       


       // "_xclick" 立即購買      


       //PayPal賬戶上的電子郵件地址      


       //物品名稱（或購物車名稱）      


       de" value="USD"> //定義幣種以標示貨幣變量 值可以為 "USD"、"EUR"、"GBP"、"CAD"、"JPY"。      


       //物品的價格（購物車中所有物品的總價格,因為是_Xclick模式）

 

 

可用變量

business 您的PayPal賬戶上的電子郵件地址

quantity 物品數量。大於 1 時，會與金額相乘

item_name 物品名稱（或購物車名稱）。必須是字母數字字符，最多為 127 個字符

item_number 用於跟蹤付款的可選傳遞變量。必須是字母數字字符，最多為 127 個字符

amount 物品的價格（購物車中所有物品的總價格）

shipping 該物品的運送成本

shipping2 每增加一件物品所需的運送成本

handling 手續費

tax 基於交易的稅額。如果使用該變量，傳遞值將覆蓋所有用戶信息稅收設置（不管買家所在位置）。

no_shipping 送貨地址。如果設為 "1"，則不會要求您的客戶提供送貨地址。該變量為可選項；如果省略或設為 "0"，將提示您的客戶輸入送貨地址

cn 可選標簽，會在提示欄上顯示（最多 40 個字符）

no_note 為付款加入提示。如果設為 "1"，則不會提示您的客戶輸入提示。該變量為可選項；如果省略或設為 "0"，將提示您的客戶輸入提示。

on0 第一選項欄名稱。最多 64 個字符

os0 第一組選項值。最多 200 個字符。"on0" 必須定義，以便識別 "os0"。

on1 第二選項欄名稱。最多 64 個字符

os1 第二組選項值。最多 200 個字符。"on1" 必須定義，以便識別 "os1"。

custom 決不會向您的客戶顯示的可選轉遞變量。可用於跟蹤存貨

invoice 決不會向您的客戶顯示的可選轉遞變量。可用於跟蹤賬單號

notify_url 僅與 IPN 一起使用。發送 IPN Form Post 的互聯網 URL

return 您的客戶完成付款後將返回的互聯網 URL

cancel_return 您的客戶取消付款後將返回的互聯網 URL

image_url 您要用作圖標的圖片的互聯網 URL，圖片大小為 150 X 50 像素

cs 設置您的付款頁面的背景色。如果設為 "1"，背景色將為黑色。該變量為可選項；如果省略或設為 "0"，背景色將為白色

擴展變量

PayPal 允許您粘貼擴展變量，條件是將改變以下 "cmd" 值：

到：

通過上述 “cmd” 值修改，您還可使用以下變量：

擴展變量

email 客戶的電子郵件地址

first_name 客戶的名。必須是字母數字字符，最多為 32 個字符

last_name 客戶的姓。必須是字母數字字符，最多為 64 個字符

address1 客戶地址所在國家或地區。必須是字母數字字符，最多為 100 個字符

address2 客戶地址第二行。必須是字母數字字符，最多為 100 個字符

city 客戶地址所在城市。必須是字母數字字符，最多為 100 個字符

state 客戶地址所在州。必須是正式的 2 個字母縮寫

zip 客戶地址的郵政編碼

night_phone_a 客戶夜間聯系電話號碼的區號

night_phone_b 客戶夜間聯系電話號碼前三位

day_phone_a 客戶白天聯系電話號碼的區號

day_phone_b 客戶白天聯系電話號碼前三位

提示：若要更改”用戶信息”中的默認運費和手續費設置，請轉至您的用戶信息，編輯您的運費計算，然後點擊”允許采用基於交易的運費”復選框。

將單個物品傳遞給PayPal

如果您的第三方購物車可設置成向PayPal傳遞單個物品，有關物品的信息將加入買家和賣家 的記錄日誌和系統通知中。要加入該物品的信息，您需要將 HTML 格式元素粘貼至PayPal購物車流程的新版本。該過程與 #1 節"將總購物車數量傳遞給PayPal"描述的非常相似，不同之處在於：

將 "cmd" 變量設置到 "_cart"

更換必要的 HTML 行與

添加稱為 “upload” 的新變量

在 <表格> 和 標簽之間新增以下行：

定義物品明細

對於以下各特定物品參數，定義與通過您的合作商購物車購買的各物品對應的一組新值。將 “_x” 附加到變量名稱，其中 x 是物品號碼，從 1 開始，每加入一物品增加一。

item_name_x （物品 #x 需要）購物車中物品 #x 的名稱。必須是字母數字字符，最多為 127 個字符

item_number_x 與購物車中物品 #x 關聯的可選傳遞變量。必須是字母數字字符，最多為 127 個字符

amount_x （物品 #x 需要）物品 #x 的價格

shipping_x 運送物品 #x 的第一件（數量 1）的成本

shipping2_x 每增加一件運送物品 #x（數量 2 或更多）所需的運送成本

handling_x 物品 #x 的處理成本

on0_x 物品 #x 的第一選項欄名稱。最多 64 個字符

os0_x 物品 #x 的第一組選項值。最多 200 個字符。”on0_x” 必須定義，以便識別 “os0_x”。

on1_x 物品 #x 的第二選項欄名稱。最多 64 個字符

os1_x 物品 #x 的第二組選項值。最多 200 個字符。”on1_x” 必須定義，以便識別 “os1_x”。

為購物車中每件物品重復此設定

為您的買家購物車中的各物品加入以上表格中的一組必需的變量和任何選項變量。購物車中的第一 物品必須用以 “_1″ 結束的參數定義，如 “item_name_1″、”amount_1″ 等。同樣，第二物品應用變量 “item_name_2″、”amount_2″ 等命名。提示：”_x” 值必須以一為單位按序遞增，以便識別。如果從 item #1 跳到 item #3 而不定義 item #2，則第三個物品會被忽略。

要指定幣種：所有貨幣變量（金額、運費、運費 2、手續費、稅款）將以粘貼在付款上的 “currency_code” 變量指定的幣種顯示。因為其不是隨物品不同的，無需向變量名稱附加 “_x”。如果沒有粘貼 “currency_code” 變量，我們將假定所有貨幣變量值為美元。

PayPay API

PayPal提供了多個API接口供開發者使用。在使用API之前，你必須先申請一個高級個人賬戶或者企業賬戶，同時你必須獲取API 憑證供每次調用API 時使用。

一旦你獲取了API憑證，您就可以調用相關的API接口了。目前，我們提供兩種API接口方式，NVP和SOAP。一般來說我們推薦您使用 NVP 接口。

 Name-Value Pair（NVP）接口 – 請求和響應都是使用簡單的HTTP。該接口簡單易實現，適合於初級開發者和需要快速完成集成的人員；

 SOAP接口 - 請求和響應都是通過SOAP來完成。該接口適合於面向對象工程的開發；

PayPal API：NVP（名稱/值對）接口

通過NVP API接口， 您只需給PayPal發送一個HTTP請求，並通過“名稱=值”的形式指定請求參數，即可充分利用PayPal的API功能。

NVP API 是 PayPal 的業務功能、風險管理和業務邏輯的簡單接口。NVP API 最基本的使用方法是通過到 PayPal 服務器的 HTTPS 連接發送一個 NVP 字符串，然後處理響應（也是一個 NVP 字符串）。執行 NVP API 調用的基本步驟如下：

 為特定的 API 方法構造一個請求參數字符串。

 通過 HTTPS 連接向 PayPal 服務器發送這個參數字符串。

 處理服務器響應中的 NVP。

每個NVP API請求字符串包含有API用戶名、API密碼、所要調用API的名稱及用來標識交易的令牌，如： USER=[e-mail]&PWD=mypassword &METHOD=GetExpressCheckoutDetails&TOKEN=EC-23T233ZP3DFB...

成功的應答包含以下要素：ACK=Success ，以及一個用來標識交易的唯一令牌。 ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000&BUILD=buildNumber  &TOKEN=EC-3DJ78083ES565113B&EMAIL=[e-mail] &PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified &FIRSTNAME=John&LASTNAME=Smith...

您可以使用NVP API完成以下操作：

 搜索已完成的交易記錄，以及查詢交易詳情；

 自動化後端功能，例如，捕獲授權，以及處理退款等；

API Profile

進入商家賬號得到相應的APIProfile，如果是以中文語言查看，在-用戶信息-API 訪問-中得到，其中裏面申請API時，有兩個選項，第一個是用簽名的方式,第二種是以證書的方式來認證商家身份，當你選擇下載數字證時，可以到  www.paypaltech.com/tools/pem2p12.php轉換為.p12文件，也可以采用OpenSSL的命令完成，一句話搞定，要輸 入密碼喔~。這裏的鏈接有詳細說明 www.paypal.com/IntegrationCenter/ic_certificate.html

相應參考資料請參考連接 www.paypal.com/IntegrationCenter/ic_expresscheckout.html 了解關於Express Checkout的原理；

在此基礎上，你可以訪問 www.paypal.com/IntegrationCenter/ic_nvp.html 獲取相關測試代碼；

關於PayPal的測試環境你可以訪問 www.paypal.com/IntegrationCenter/ic_sandbox.html,

API Reference  https://www.paypal.com/IntegrationCenter/ic_api-reference.html