概述
環境 Domain
以下為串接時可使用的環境 Domain:
- 正式環境:https://api.payments.91app.com
- 開發者環境:https://api.developer.payments.91app.com
串接時必要資訊
API 串接資訊 | 說明 | 取得/提供方式 |
|---|---|---|
| N1-API-KEY | 呼叫方的驗證授權,請置於 API 呼叫時的 header 中 | 與 91APP Payments 完成申請後提供。(於申請完成結果回覆檔的 Api Key) |
| sharedSecret | 計算 N1-DATA-SIGNATURE 需要的 secret | 與 91APP Payments 完成申請後提供。(於申請完成結果回覆檔的 IV Key) |
| N1-DATA-SIGNATURE | API Payload 資料完整性驗證,請置於 API 呼叫時的 header 中 | 透過 API Path 與 Payload 計算 HMAC-SHA256,可參考下面範例 |
| 91APP Payments IP | 91APP Payments 有提供交易結果通知,若商店有針對 IP 進行管控,請將 91APP Payments 的對應 IP 加入白名單 | 與 91APP Payments 完成申請後提供給商店 |
| 商店 IP | 91APP Payments 除 API Key 的存取控管外,亦會針對 IP 作管控,請於申請時提供貴商店發送 API 的固定 IP 以利加入白名單 | 申請時提供給 91APP Payments |
N1-DATA-SIGNATURE 計算範例
- C#
- PHP
void Main()
{
var sharedSecret = "sampleSecret";
// 1. HTTP POST Method 的簽章範例
var requestBody = new { Sample = "sample" };
var jsonString = JsonConvert.SerializeObject(requestBody);
Console.WriteLine(jsonString);
// {"Sample":"sample"}
var hmacContentForPost = SignHMAC(jsonString, sharedSecret).ToLower();
var signatureForPost = Convert.ToBase64String(Encoding.UTF8.GetBytes(hmacContentForPost));
Console.WriteLine(signatureForPost);
// ZjY0ZDViYTljMTQ1NWY0ODU5MDAwZjIwZDliNDBjYTAxNjNjNWFiMmQwNzBkM2NjODgyYjY3N2MzNjM4YWY3Yg==
// 2. HTTP GET Method 的簽章範例
var scheme = "https";
var host = "api.developer.payments.91app.com";
var path = "/v2/trades/sample";
var uriBuilder = new UriBuilder(scheme, host);
uriBuilder.Path = path;
var query = HttpUtility.ParseQueryString(uriBuilder.Query);
query.Add("q", "test");
uriBuilder.Query = query.ToString();
// 注意:需要移除 path 與 query string 間的問號
var inputData = uriBuilder.Uri.PathAndQuery.Replace("?", string.Empty);
Console.WriteLine(inputData);
// /v2/trades/sampleq=test
var hmacContentForGet = SignHMAC(inputData, sharedSecret).ToLower();
var signatureForGet = Convert.ToBase64String(Encoding.UTF8.GetBytes(hmacContentForGet));
Console.WriteLine(signatureForGet);
// OTcxOWIyZTZmZGZlYjkyZjA4M2U1ZTc4MmQxMDg4NjQzMTk3Zjg0NmYwOWJjMDkzYzZlMWM1MTBkNTU2ZDQ2OA==
}
public string SignHMAC(string inputData, string sharedSecret)
{
var encoding = new UTF8Encoding();
var keyByte = encoding.GetBytes(sharedSecret);
var messageBytes = encoding.GetBytes(inputData);
using (var hmacSHA256 = new HMACSHA256(keyByte))
{
var hashMessage = hmacSHA256.ComputeHash(messageBytes);
return BitConverter.ToString(hashMessage).Replace("-", string.Empty);
}
}
<?php
// 串接端請確保在組合 API request payload 並提供給 API client(e.g. curl) 時,有與簽章的 json_encode 是一致的處理方式
$sharedSecret = "sampleSecret";
// 1. HTTP POST Method 的簽章範例
$requestBody = ["Sample" => "sample"];
$jsonString = json_encode($requestBody);
$signature = signHMAC($jsonString, $sharedSecret);
echo $signature . "\n";
// ZjY0ZDViYTljMTQ1NWY0ODU5MDAwZjIwZDliNDBjYTAxNjNjNWFiMmQwNzBkM2NjODgyYjY3N2MzNjM4YWY3Yg==
// 2. HTTP GET Method 的簽章範例
$scheme = "https";
$host = "api.developer.payments.91app.com";
$path = "/v2/trades/sample";
$uri = $scheme . "://" . $host . $path;
$query = http_build_query(['q' => 'test']);
$uri .= '?' . $query;
// 如果有 query string,要移除 path 與 query string 間的問號
$inputData = str_replace('?', '', parse_url($uri, PHP_URL_PATH) . '?' . parse_url($uri, PHP_URL_QUERY));
echo $inputData . "\n";
// /v2/trades/sampleq=test
$signatureForGet = signHMAC($inputData, $sharedSecret);
echo $signatureForGet . "\n";
// OTcxOWIyZTZmZGZlYjkyZjA4M2U1ZTc4MmQxMDg4NjQzMTk3Zjg0NmYwOWJjMDkzYzZlMWM1MTBkNTU2ZDQ2OA==
// 計算 HMAC 簽名
function signHMAC(string $data, string $sharedSecret): string
{
$hmacString = hash_hmac('sha256', $data, $sharedSecret, false);
$convertToUtf8Context = mb_convert_encoding(strtolower($hmacString), 'UTF-8', 'ISO-8859-1');
return base64_encode($convertToUtf8Context);
}
?>
各 API 摘要說明
| 類型 | API 名稱 | API Path | 說明 | 狀態 |
|---|---|---|---|---|
| 交易請求 | 透過txnToken進行交易 | /v2/payments/request-by-txnToken | 消費者於 SDK 中輸入信用卡資訊後,SDK 會回覆 txnToken,可使用該組 txnToken 搭配此 API 送出交易請求 | 可供串接 |
| 交易請求 | 透過cardToken進行交易 | /v2/payments/request-by-cardToken | 若前次交易選擇記住卡號,則 91APP Payments 會回傳 cardToken,付款成功後,後續商店可用該 cardToken 請求交易 | 可供串接 |
| 交易請求 | 付款頁連結建立 | /v2/pay-pages/url | 建立一個 91APP Payments 的付款頁讓消費者進行付款 | 可供串接 |
| 交易請求 | 付款頁連結取消 | /v2/pay-pages/cancel | 將已產生的付款頁連結作廢 | 可供串接 |
| 查詢 | 交易查詢 | /v2/trades/{tradeId} | 用以查詢指定交易當前狀態 | 可供串接 |
| 查詢 | 交易歷程查詢 | /v2/trades/{tradeId}/record | 用以查詢指定交易的狀態歷程 | 可供串接 |
| 請退款 | 請款申請 | /v2/trades/{tradeId}/capture | 針對指定交易執行請款請求 | 可供串接 |
| 請退款 | 請款取消 | /v2/trades/{tradeId}/capcancel | 針對指定交易執行請款取消 | 可供串接 |
| 請退款 | 授權取消/退款申請 | /v2/trades/{tradeId}/refund | 針對指定交易執行退款申請 | 可供串接 |
| 交易取消 | 交易取消 | /v2/trades/{tradeId}/cancel | 針對指定交易執行交易取消,目前僅支援超商代碼交易可以操作 | 可供串接 |
| 活動 | 信用卡活動 BIN 碼驗證 | /v2/promotion-bin-code/verify-bin-code | 驗證是否有符合特定支付方式的對應活動 | Preview 版本, 尚未提供串接 |
| 帳務 | 平台出帳 | /v2/ledgers/transfers | 推廣商向合作商店發動出帳作業 | 可供串接 |
| 帳務 | 平台扣帳 | /v2/ledgers/charges | 推廣商向合作商店發動扣款作業 | 可供串接 |
| 帳務 | 平台帳務交易查詢 | /v2/ledgers/requests/{transferCode} | 推廣商可查詢平台帳務請求交易當前狀態 | 可供串接 |
| 帳務 | 平台帳務交易取消 | /v2/ledgers/requests/{transferCode}/cancel | 推廣商可取消已請求的平台帳務交易 | 可供串接 |
| 帳務 | 虛擬帳戶餘額查詢 | /v2/ledgers/{storeCode}/virtual-account | 推廣商可查詢指定商店的虛擬帳戶餘額資訊 | 可供串接 |
| 帳務 | 虛擬帳戶帳務查詢 | /v2/ledgers/transactions | 查詢指定商店的虛擬帳戶的帳務資料 | 可供串接 |
| 帳務 | 帳務明細查詢 | /v2/ledgers/entries | 查詢商店帳務明細資料 | 可供串接 |
