概述

環境 Domain​

以下為串接時可使用的環境 Domain：

• 正式環境：https://​api.payments.91app.com
• 開發者環境：https://​api.developer.payments.91app.com

串接時必要資訊​

N1-DATA-SIGNATURE 計算範例​

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 摘要說明​

使用情境/流程​

輸入信用卡號交易​

記住卡號交易​

儲值金串接​

支付後儲值​

交易請求需帶入商品類型(ProductType)為儲值商品(StoredValue)， 支付成功後會回傳 儲值驗證Token (StoredValueToken)，商店端可使用該 儲值驗證Token 進行儲值金的儲值操作。 正常情況下，儲值金的儲值操作不會失敗，但若儲值失敗，商店端可透過客服退款的方式處理。

目前僅支援以下付款方式：

• CreditCard (信用卡)
• ApplePay (Apple Pay)
• ATM (ATM轉帳)

不需轉導至外部交易頁​

情境：

• 信用卡一般授權
• ApplePay

需轉導至外部(3D)交易頁或等待消費者操作​

情境：

• 信用卡 3D 交易驗證
• ATM 轉帳

儲值金付款​

在一些情況下，消費者剩餘的儲值金不足以支付當前交易金額，或是消費者希望使用儲值金支付部分金額，剩餘金額則使用其他支付方式支付。 在這種情況下，當其中一種支付方式失敗時，商店端應該要能夠處理這種情況。

1. 使用順序建議為：儲值金 > 其他支付方式。
2. 當其它支付方式失敗時，商店端應該要能夠取消儲值金的交易請求 ，以避免消費者的儲值金被扣除。
3. 正常交易退款請使用 退款 API 。

下圖示範了如何同時使用儲值金付款與其它支付方式付款(以信用卡為例)，並處理支付失敗的情況。

大哥付你分期​

大哥付你分期部分交易可能進入審核流程（詳見 大哥付你分期官網），此時交易狀態將為付款處理中（recordStatus=8）。
商店須等待最終審核通知，收到付款處理中時不可完成交易，待 91APP Payments 發送最終結果通知後方可處理。

注意事項：

• 最終交易結果通知與第一次交易結果通知格式相同，以 recordStatus 判斷最終結果。

交易測試資訊​

開發者平台環境測試串接使用的工具，可供整合流程使用。

信用卡​

• 信用卡： 以下測試卡號對應的有效年月請輸入 2034 年 12 月(即 12/34)；CVV 驗證碼規則為：AMEX 使用任意四碼，其他信用卡使用任意三碼。
• 國外卡不可分期

Apple Pay​

在開發環境中測試 Apple Pay 串接時，可以以你的真實 Apple Pay 中的信用卡來做測試，並取得 txnToken，使用真實信用卡測試的交易將會回應固定的信用卡資訊及 txnToken，開發者環境的 Apple Pay 不會扣款，請安心使用。如需測試各種交易場景，可使用以下 txnToken 來模擬不同的交易結果，確保 Apple Pay 功能在不同情況下都能正確運作。

Google Pay​

在開發環境中測試 Google Pay 串接時，可以以你的真實 Google Pay 中的信用卡來做測試，並取得 txnToken，使用真實信用卡測試的交易將會回應固定的信用卡資訊及 txnToken，開發者環境的 Google Pay 不會扣款，請安心使用。如需測試各種交易場景，可使用以下 txnToken 來模擬不同的交易結果，確保 Google Pay 功能在不同情況下都能正確運作。

大哥付你分期​

在開發環境中測試大哥付你分期串接時，請使用以下測試帳號模擬消費者登入大哥付付款頁面進行分期付款。

推廣商帳務測試資訊​

帳務執行日​

於 平台出帳 及 平台扣款 API 中欄位設定，可預約帳務交易在 N 天後執行，設定 0 的話則是當日執行

• 當日執行：系統於每小時批次執行
• 預約執行：因測試與正式環境有所差異，請參考下方各環境說明
  • 正式環境：將在預約當日上午執行
    • 若在 4 / 21 發動 平台出帳 或 平台扣款 請求且帳務執行日為 3 天，系統將在 4 / 24 上午執行
    • 帳務交易執行結果在上午 11 點後可供查詢
  • 測試環境：於預約當日零時執行

帳務交易測試情境​

測試環境中的帳務交易結果均會成功處理，不會有失敗的帳務交易

成功/失敗情境​

• 成功情境: 交易金額必須設定為 ≦ 5,000
• 失敗情境: 交易金額設定為 > 5,000 時，可以取得請求失敗的案例

儲值金測試資訊​

儲值金提領​

商店端可使用儲值金提領申請 API 進行儲值金的提領操作。
在開發者平台環境測試中，儲值金提領的狀態會停留在 提領申請 的狀態。商店可以透過儲值金提領更新API 將該提領申請取消，除此之外，開發環境中不會有其他狀態的變化。

名詞說明​

列舉定義​

交易狀態/recordStatus​

請款狀態/captureStatus​

商品類型/productType​

支付方式/payType​

幣別/currency​

馬來西亞令吉 (MYR)、新加坡元 (SGD)、泰銖 (THB)、越南盾 (VND)、菲律賓披索 (PHP)、印尼盾 (IDR)交易時，僅支援 RMS 的交易。

N1-IDEMPOTENCY-KEY說明​

非必填，若未填表示不使用 Idempotency 機制

Idempotency 機制​

目的：避免 API 傳輸過程因網路延遲或其他因素，造成應用程式例外或資料不一致...等意料之外的錯誤
相同的 Idempotent Key及 Request 資訊，一小時內執行第二次以上會得到同樣的結果

Idempotency 錯誤處理​

當使用相同的 Idempotent Key，但是 Request 資訊與上次不一致，會拋出錯誤
HTTP 400 BadRequest：{ "errorCode" : "IdempotentError" , "message" : "請求不一致" }

當同時間有相同的 Idempotent Key 及 Request 資訊，但第一個 Request 尚未完成，第二個 Request 會拋出錯誤
HTTP 409 Conflict：{ "errorCode" : "IdempotentConflict" , "message" : "請求衝突，請稍後再試" }
這時候可以進行 Retry，直到第一個 Request 完成，第二個 Request 就會取得同樣的結果