Skip to main content

ApplePay串接

介接準備說明​

  1. 商店需有 APPLE 的開發者帳號(個人/公司)
  2. 使用開發者帳號完成開發者前置準備
  3. 將以下資料寄件至 service@paynow.com.tw 信箱
    1. PayNow統編
    2. Apple Pay 的 MerchantID(merchant.xxx.xxx)
    3. 建立憑證開始需電洽PayNow:02-2521-5088
  4. 商家需自行串接 三段程式
    1. APPLE PAY的付款交易(Apple Pay JS)
    2. PayNow 商家驗證
    3. PayNow 金流授權
  5. 付款頁面，UI設計需遵守APPLE PAY規範
  6. Apple Pay交易環境必須支援TLS 1.2
  7. Apple Pay僅接受實體商品業者

ApplePay開發前置Setting​

Step 1. 商家Apple帳戶設定​

1.1 登入至您的 Apple​

登入網址:https://developer.apple.com/account/

paymentflow

1.2 選擇「Certificates, Identifiers & Profiles」​

paymentflow

1.3 點選「Identifiers」並點選 「+」號新增​

paymentflow

1.4 點選「Merchant IDs」註冊商務資料​

paymentflow

1.5 填入 「Description」 及 「Identifiers」​

Ps. 「Identifiers」建議填入 反序的 Domain，前面自動出現的 「merchant.」為正常情況

paymentflow

1.6 點選Register完成註冊​

paymentflow

以下步驟需聯絡PayNow客服 02-2521-5088，並將以下資料寄件至service@paynow.com.tw信箱

  • PayNow 統編

  • Apple Pay 的 MerchantID(merchant.xxx.xxx)

客服將給予一個檔案供商家建立交易憑證


Step 2. 建立交易憑證​

2.1 點選剛註冊好的 Merchant IDs​

paymentflow

2.2 點選Apple Pay Payment Processing Certificate 下的「Create Certificate」按鈕​

paymentflow

2.3 回答問題，選擇「No」並點選「Continue」繼續​

paymentflow

2.4 上傳PayNow提供之檔案(檔案名稱為「applepayment_processing_certificate商家統編」)​

paymentflow

2.5 下載檔案傳送給 PayNow，將再次給予另一個檔案供商家建立商家憑證​


Step 3. 建立商家憑證​

3.1 點選剛註冊好的Merchant IDs​

paymentflow

3.2 點選Apple Pay Merchant Identity Certificate 下的「Create Certificate」按鈕​

paymentflow

3.3 上傳PayNow 提供之檔案(檔案名稱為「applemerchant_identity_certificate商家統編」)​

paymentflow

3.4 將檔案下載並傳送給PayNow​

Step 4. 設定商家Domain​

4.1 點選Merchant Domains下的Add Domain按鈕​

paymentflow

4.2 輸入付款頁面網站的Domain​

paymentflow

4.3 下載指定檔案，並於該 Domain 下新增名為「.well-known」資料夾，放入剛下載的「apple-developer-merchantid-domain-association.txt」再點選「Verify」​

參考資料: https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server

paymentflow


ApplePay 信用卡串接說明​

交易流程圖

paymentflow

功能流程說明​

  1. Apple Pay 付款檢查
  2. 建立 Apple Pay Session 物件
  3. 消費者按下按鈕，進行商店驗證（前端）
  4. 傳送資訊至後端呼叫「PayNow 商家驗證」商家驗證（後端）
  5. 將「PayNow商家驗證」回傳值pass給ApplePaySession的 「completeMerchantValidation」
  6. 消費者進行指紋驗證授權交易，傳送資訊至後端呼叫「信用卡授權」付款授權（後端）
  7. 將「信用卡授權」回傳值，進行付款授權（前端）

付款頁面設計​

  1. Apple Pay 營銷準則 參考網址：https://developer.apple.com/apple-pay/marketing/

  2. 付款按鈕樣式規範 參考網址：https://developer.apple.com/design/human-interface-guidelines/apple-pay/overview/buttons-and-marks/

    範例： 

    <div id="btnApplePay" class="apple-pay-button apple-pay-button-black" 
       style="-webkit-appearance: -apple-pay-button; -apple-pay-button-type: buy; width: 200px;
       height: 64px;">
    </div>

  3. 付款按鈕 CSS樣式

    參考網址：https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons

    範例：

    /* CSS */
    @supports (-webkit-appearance: -apple-pay-button) {
       .apple-pay-button {
          display: inline-block;
          -webkit-appearance: -apple-pay-button;
       }
       .apple-pay-button-black {
          -apple-pay-button-style: black;
       }
    }

    @supports not (-webkit-appearance: -apple-pay-button) {
       .apple-pay-button {
          display: inline-block;
          background-size: 100% 60%;
          background-repeat: no-repeat;
          background-position: 50% 50%;
          border-radius: 5px;
          padding: 0px;
          box-sizing: border-box;
          min-width: 200px;
          min-height: 32px;
          max-height: 64px;
       }
       .apple-pay-button-black {
          background-image: -webkit-named-image(apple-pay-logo-white);
          background-color: black;
       }
    }

ApplePay付款檢查​

功能說明：檢查是否支援 ApplePay 付款

參考網址：https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession#2166537

範例：

/* 檢查當前瀏覽器是否支援Apple Pay */
if (window.ApplePaySession) {
   var merchantIdentifier = 'Apple Pay Merchant ID'; //填入你申請的Apple Pay Merchant Identifier
   
   /* 檢查設備是否能夠支援Apple Pay付款，它不會驗證用戶在電子錢包中是否有綁定卡片 */
   if (ApplePaySession.canMakePayments()) {
      /* 檢查付款設備是否能夠支援Apple Pay付款，且用戶在電子錢包中必需綁定一張卡片 */
      /* 若Safari設定中的「檢查ApplePay設定」關閉時canMakePayments一律回傳True */
      var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
      promise.then(function (canMakePayments) {
         if (canMakePayments) {
            $("#btnApplePay").click(beginPayment);
            //顯示ApplePay按鈕
            $("#PayMentDiv").show();
         }
         else {
            /* 無綁定卡片無法進行ApplyPay*/
            /* 執行錯誤提示或進行頁面跳轉*/
         }
      });
   }
   else {
      /* 此設備不支援ApplePay */
      /* 執行錯誤提示或進行頁面跳轉 */
   }
}
else {
   /* 無法支援Apple Pay的相關處理 */
   /* 執行錯誤提示或進行頁面跳轉 */
}

建立 Apple Pay Session物件​

功能說明：設定付款物件，初始化 Apple Pay Session 物件

參考網址：https://developer.apple.com/reference/applepayjs/paymentrequest

範例：

/* 建立 PaymentRequest */
/* 參考: https://developer.apple.com/reference/applepayjs/paymentrequest */
var request = {
countryCode: 'TW', //國家代碼請填 TW
currencyCode: 'TWD',//幣別僅接受 TWD
supportedNetworks: ['visa', 'masterCard','jcb'],//卡別僅支援 visa masterCard jcb
merchantCapabilities: ['supports3DS'], //付款方式僅支援 supports3DS
lineItems: [{ label: '測試商品', amount: $("#Amount").val() }],//商品資訊
total: { label: 'PayNow,Inc', amount: $("#Amount").val() } //商品統計
};
/* 建立 ApplePaySession */
/* 參考:https:/developer.apple.com/reference/applepayjs/applepaysession/2320659-applepaysession */
var session = new ApplePaySession(2, request);

商店驗證(前端)​

功能說明：將 ValidationURL 傳送到 Server 端，向 PayNow 發送請求驗證是否來自有效的商家。

範例：

/* 商店驗證事件 */
session.onvalidatemerchant = function (event) {
   /* 將ValidationURL拋到Server端，向PayNowAPI發送請求 */
   $.ajax({
      url: 'Server URL',
      method: "POST",
      data:
      {
         ValidationURL: event.validationURL
      },
      error: function (err) {
         /* 執行錯誤提示或進行頁面跳轉*/
         session.abort();
      }
   }).then(function (TransactionSession) {
      /* 取得Server回傳資訊 */ 
      session.completeMerchantValidation(JSON.parse(TransactionSession)); 
   });
};

付款授權（前端）​

功能說明：向PayNow發送請求授權，依授權結果決定帶入ApplePaySession回應

範例：

/* 進行付款授權事件 */
session.onpaymentauthorized = function (event) {
   /* 將payment物件拋至Server端，由Server端處理交易授權 */
   $.ajax({
      url: 'Server URL',
      method: "POST",
      data:
      {
         /* 依照 */
         Amount: $("#Amount").val(),
         payment: JSON.stringify(event.payment.token.paymentData)
      },
      error: function (err) {
         /* 執行錯誤提示或進行頁面跳轉*/ 
         session.abort();
      }
   }).then(function (result) {
      /* 依授權結果決定帶入ApplePaySession的回應 */
      /* 參考: https://developer.apple.com/reference/applepayjs/applepaysession/1778012-completepayment */
      if (result.substr(0, 2) == "S_") {
         //執行交易完成的動作
         $("#divReMsg").html("<pre>交易完成</pre>");
         session.completePayment(ApplePaySession.STATUS_SUCCESS);
      }
      else {
         //執行交易失敗的動作
         /* 執行錯誤提示或進行頁面跳轉*/
         session.completePayment(ApplePaySession.STATUS_FAILURE);
      }
   }
}

PayNow商家驗證​

  1. 路徑：https://mpay.paynow.com.tw/api/ApplePay/GetTransactionSession

  2. 傳遞方式：Http POST method

    Request

    參數名稱型態長度必須備註
    DisplayName顯示的商店名稱stringEx.PayNow
    DomainName註冊的Domain名稱stringEx.mpay.paynow.com.tw
    MemCidPayNow商家帳號stringPayNow 商家帳號
    MerchantIdentifierApple Pay MerchantIDstringEx.merchant.xxx.xxx
    ValidationURLevent.validationURL值string前端取得的值
    Signature商家驗證檢查碼string檢查碼

    Response

    參數名稱型態長度必須備註
    MemCid顯示的商店名稱stringPayNow 商家帳號
    MerchantIdentifier註冊的Domain名稱stringEx. merchant.xxx.xxx
    ErrMsgPayNow商家帳號string
    TradeStatusApple Pay MerchantIDstringS：成功 Ｆ：失敗
    TransactionSessionevent.validationURL值string請以物件傳送給ApplePaySession呼叫 completeMerchantValidation
    Signature商家驗證檢查碼string失敗將原值回傳，成功回傳檢查碼

APPLE開發者帳號申請說明​

ApplePay 開發者帳號註冊需求​

  1. 需有APPLE ID若無則需先註冊

    1. 註冊網址：https://appleid.apple.com/account 且需Apple ID 雙重認證(Two-factor Authentication)

    參考網址：https://support.apple.com/zh-tw/HT204915

    Ps.若無雙重驗證將會無法進行開發者帳號註冊

    paymentflow

  2. APPLE 開發者帳號申請

  3. 個人帳號

    • 僅限開發者自己
    • 不需填寫公司的鄧百氏編碼（D-U-N-S Number）
    • 若有 App 則上架僅能顯示個人資訊(某些類別 App 無法通過個人帳號上架)

  4. 公司帳號

    • 允許多個開發者協作
    • 需填寫公司的鄧白氏編碼（D-U-N-S Number）
    • 若無註冊鄧白氏碼，需花費較長時間申請

開發者帳號申請流程​

  1. 點選申請網址並開始註冊

    paymentflow

  2. 輸入註冊資訊，再按下「Continue」按鈕

    以下為欄位中英對照

    paymentflow

    paymentflow

    注意！羅馬式聯繫信息(Romanized Contact Information)欄位皆需輸入「英文」

  3. 選擇註冊開發者帳號類型，再按下「Continue」按鈕

    paymentflow

  4. 個人註冊

    1. 閱讀完條款並打勾，再按下「Continue」按鈕

    paymentflow

    1. 完成後續付款作業後，等待帳號激活即可

    paymentflow

  5. 公司註冊

    1. 公司註冊需擁有 DUSN 號碼 註冊DUSN號碼也可直接點擊「Check now>」連至以下網址若已有 DUSN 號碼則按下「Continue」按鈕

    參考網址：https://developer.apple.com/enroll/duns-lookup （需登入Apple ID）

    paymentflow

    1. 填寫公司名稱及 DUNS 編號及驗證碼，再按下 「Continue」按鈕

    paymentflow

    1. 填寫完成資料後請按下「Continue」按鈕

    paymentflow

    1. 填寫完成資料後請按下「Submit」按鈕

    paymentflow

    1. 申請完成後您將收到 Apple 的通知信請耐心等候後續的申請步驟

    paymentflow

    paymentflow

    1. 申請APPLE鄧白氏號碼

      請到https://developer.apple.com/support/D-U-N-S/ 點選D-U-N-S Number look up tool

      paymentflow


附錄​

1. 商家驗證(後端)檢查碼​

1.1 說明​

  • POST 時「ValidationURL」參數不需加入檢查碼，其餘參數將皆需加入檢查碼，當檢查碼錯誤時將會直接回傳 HttpStatusCode 400。
  • 回傳時「TransactionSession」參數不需加入檢查碼，其餘參數將皆需加入檢查碼，當檢查碼，失敗時將回傳原 POST 時的檢查碼，請務必確認檢查碼是否相同。

1.2 POST時檢查碼組成​

1.2.1 將參數依照英文字母，由Ａ到Ｚ的順序排序，若字母相同則以下一個字母判斷，以此類推，並將參數名稱與該參數值串聯

DisplayNamePayNowDomainNamempay.paynow.com.twMemCid28229955MerchantIdentifiermerchant.tw.com.paynow.pay

1.2.2 將字串全部轉換成小寫後做UrlEncode

displaynamepaynowdomainnamempay.paynow.com.twmemcid28229955merchantidentifiermerchant.tw.com.paynow.pay

1.2.3 將字串做SHA256，加密Key為商家PayNow交易密碼，此範例以「1234567890」加密

613B0106B509B252C3D9468723FC7A75DD69101624353646E608F3E3C44E3A31

1.2.4 將加密後的字串再次轉換成全部小寫，放入Signature傳遞給PayNow

613b0106b509b252c3d9468723fc7a75dd69101624353646e608f3e3c44e3a31

1.3 回傳時檢查碼組成(僅成功呼叫，失敗呼叫將以原POST值回傳)​

1.3.1 將參數依照英文字母，由Ａ到Ｚ的順序排序，若字母相同則以下一個字母判斷，以此類推，並將參數名稱與該參數值串聯

ErrMsgMemCid28229955MerchantIdentifiermerchant.tw.com.paynow.payTradeStatusS

1.3.2 將字串全部轉換成全部小寫

errmsgmemcid28229955merchantidentifiermerchant.tw.com.paynow.paytradestatuss

1.3.3 將字串做SHA256，加密Key為商家PayNow交易密碼，此範例以「1234567890」加密

184EA4BE92C23FF2B5FEA71929616098E22E651FA26D6AA1BD0FB57AA16C82F0

1.3.4 將加密後的字串再次轉換成全部小寫，放入Signature回傳給商家

184ea4be92c23ff2b5fea71929616098e22e651fa26d6aa1bd0fb57aa16c82f0


2. 信用卡授權​

環境位址​

  • 正式環境WSDL： https://www.paynow.com.tw/WS_CardAuthorise_JS.asmx
  • 測試環境WSDL： https://test.paynow.com.tw/WS_CardAuthorise_JS.asmx

說明​

  • 引用函式：CardAuthorise_P
  • 傳遞方式：HTTP POST Method
  • 所有參數傳遞時，請以URL Encode 編碼，所有網頁字集為UTF-8
  • 正式、測試環境為個別獨立空間，帳號需個別申請，無法共通使用

檢核碼使用的AES256加密key及IV固定為下： Key：paynowencryptpaynowcomtw28229955 IV：encrypt282299550

參數說明

參數名稱型態長度必須備註
JStr/JStr2信用卡交易內容stringY將下列參數組成Json字串且以檢核碼系統發出的Key及IV做AES256加密後，將加密後字串對分拆解成JStr及JStr2兩個參數(長度對半拆解)，再做UrlEncode上傳
mem_cid服務代號string8-10Y
TimeStr時間戳string10Y加密傳送字串時使用的TimeStr
CheckNum時間戳string10Y加密傳送字串取得隨機檢查碼時回傳的CheckNum

Json Content​

參數名稱型態長度必須備註
mem_cid商家帳號(統編/身分證)stringY
mem_checkpw交易密碼stringY
OrderNo商家自訂編號stringY
OrderInfo消費資訊stringY
ECPlatformEC名稱stringY
ReceiverID消費者帳號stringY
ReceiverEmail消費者 EmailstringY
ReceiverName消費者姓名stringY
ReceiverTel消費者電話stringY
TotalPrice交易總金額stringY
PassCode交易驗證碼stringY將以下的順序組合起來成一字串:(mem_cid & OrderNo & Total Price & mem_checkpw)並使用SHA-1雜湊函數取得組合字串的雜湊值(不含&符號)

Response

參數名稱型態長度必須備註
WS回應stringYObject型態資料組成Json字串，以檢核碼系統發出Key及IV做AES256加密後回傳，請以檢核碼系統發出Key及IV做AES256解密

Json Content

參數名稱型態長度必須備註
WebNo統編/身分證stringY商家帳號
BuysafeNoPayNow訂單編號stringY
OrderNo商家自訂編號stringY
RespCode授權回覆代碼stringY
TotalPrice交易總金額stringY
TranStatus交易結果stringY回傳S代表交易成功；F代表交易失敗
ResponseMSG授權回覆訊息stringY
ApproveCode信用卡授權碼stringY
PassCode驗證碼stringY以下參數值依序組合起來成一段字串(不包含+號) : WebNo + mem_checkpw + BuysafeNo + TotalPrice + RespCode並使用sha-1雜湊函數取得組合字串的雜湊值sha-1雜湊函數
last4CardNo卡號末四碼stringY
CIFID_SN預存授權帳號流水號stringY請妥善保存
ErrorMessage錯誤描述string200Y錯誤訊息(若有錯誤時產生，沒有錯誤則無)