識別碼 (Identifier) & ReferenceId

Identifier 用於追蹤錢包，而 ReferenceId 則用於追蹤存款與提款。

注意：本頁的代碼應視為偽碼 (pseudocode)。有關詳細資訊和完全正确的範例，請參閱說明文件中描述特定功能的頁面。

重要事項

  • 存款地址會永久映射至其建立時的識別碼 (identifier)

  • 傳送至此類地址的交易總會包含識別碼 (identifier)

  • referenceId 在存款請求中是可選的。如果您同時管理存款請求，它可以讓您進一步識別用戶存入的是哪筆存款。

    • 注意：Reference-Id 會在 24 小時後過期。存款仍可存入相關地址，但 referenceId 將不會出現在回調中。

    • 如果您使用相同的識別碼 (identifier) 和網路新增多個 referenceId，只要它們尚未過期，就會依序傳回，最舊的先傳回。(除非使用不同的請求金額）

  • 在出款請求中，referenceId 為必填欄位，可用於識別單筆付款交易。

強烈建議在使用者和存款地址之間保持一對一的對應關係。

為什麼？

  • 永久分配的存款地址意味著每次啟動存款（或通過某種演算法從預先產生的池中選擇）時都不必創建新的錢包。為一個識別碼 (identifier) 請求一個存款地址後，您知道該識別碼 (identifier) 和地址是永遠相連的，因此不需要再為該識別碼 (identifier) 請求存款地址。如果您仍想檢查地址，AP 只需在資料庫中查找該錢包，而不是在區塊鏈上創建一個新錢包 - 這可能是一個冗長的過程，因此仍然更有效率。

  • 如果您管理的是一組用戶，您會更容易追蹤哪個用戶有哪個地址用於存款（因為只有一個，而且總是同一個）。同樣地，您的用戶只需處理一個地址（或確實是每個網絡一個）用於存款，將存款進入錯誤錢包的任何風險降至最低。

詳細說明

在文件和程式碼中，您會遇到「識別碼」 (identifier)的概念。識別碼 (identifier) 就是唯一識別存款地址。通常，識別碼 (identifier) 會是 userId 或類似的東西，但如何使用則由您決定。

如果您管理存款請求，您可以將您的存款 ID 傳給 「referenceId」，以進一步識別用戶存入的是哪筆存款。

如果您管理出款請求，您可以直接將您的出款 ID 傳給 「referenceId」，它將在回調中作為 「referenceId」 返回。

存款

建立存款地址

您最先遇到識別碼 (identifier) 的地方通常是為您的軟體建立錢包（存款地址）時，也許是讓您的某位使用者將資金存入錢包。如果您控制著許多使用者，您很可能會以一些獨特的屬性（例如 ID 或使用者名稱）儲存他們的資料。這可以用來取得存款地址：

AkashicPay.getDepositAddress("TRX", "user1");
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'

回調的地址 (上例中為 TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb) 現在永久指定給識別碼 'user1'。之後任何相同函式 (function) 的回調都會傳回相同的地址：

AkashicPay.getDepositAddress("TRX", "user1");
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'

如果您變更網路或識別碼 (identifier)，自然會得到不同的地址：

AkashicPay.getDepositAddress("TRX", "user2");
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress("ETH", "user1");
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (diffrent format on Ethereum)

如果您需要將存款對應到您的存款請求，您需要將存款請求 ID 傳給 referenceId

AkashicPay.getDepositAddress("TRX", "user2", "order1");
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress("ETH", "user1", "order2");
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (diffrent format on Ethereum)

存款回調

如果我們已經識別為 user1 的用戶現在決定向錢包 TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb 入金，您將收到一個回調到您在 AkashicPay.com 上設定的 URL。回調物件中會有一個標題為識別碼 (identifier) 的欄位，其值為 user1。這可以讓您輕鬆地將存款與其所屬的用戶相識別。當然，如果您願意的話，也可以將地址 (TTV...) 儲存在資料庫中，然後用它來代替。

如果您在 getDepositAddress 中傳入 referenceId，您也會在回調中收到 referenceId。

出款/提款

處理出款（提款）

對於出款/提款，必須在函式呼叫中包含 referenceId。referenceId 必須能用來識別該筆付款交易。

AkashicPay.payout('tx1', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('tx2', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '5', 'TRX', 'USDT')

這將在 Tron (TRX) 網絡上啟動一筆從 AkashicPay 到外部錢包 TAzsQ... 的交易，價值為 10 USDT。由於 AkashicPay 的工作方式，提款可能會從許多錢包中的一個發送。因此，不能保證（事實上，不太可能）取款是從用來存款的相同地址發送的，您絕對不應該相信這一點。

但是，基於上述原因，我們強烈建議存款時不要使用此方法。

出款回調

當使用上述功能觸發提款時，您將再次收到一個回調到您在 AkashicPay.com 上設置的 URL。當您收到出款回調時，交易已經被確認，並且可以安全地將款項存入用戶的賬號中。

特殊案例

付款時沒有referenceId？

根據您的使用情況，有些情況下可能不需要包含 referenceId。例如，向特殊錢包進行內部交易或進行利潤出款時。一般而言，對於這些與任何使用者無關的出款，referenceId 基本上是多餘的。但是，我們仍然要求所有交易都要有referenceId，以確保所有交易都能被清楚追蹤。這是由於沒有安全的方法來分開兩個交易，否則在技術上有可能同時發生兩個原本相等的交易。因此，我們鼓勵您使用合理的referenceId 記錄所有交易。例如：

AkashicPay.payout('INTERNAL_TRANSFER', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('PROFIT_PAYOUT', 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', '1000', 'TRX', 'USDT')

當然，任何字串參數 (string-argument) 都是允許的，所以如果您絕對確定不想透過referenceId來追蹤交易，您可以直接提供任何隨機字串 (string)，然後馬上忘記它：

注意！請勿使用空字串 (string)！

AkashicPay.payout('foo', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('NaN', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

多個存款地址？

當然，沒有什麼可以阻止您在系統中為「user1」提供多個存款地址。也許一個地址會用於特別促銷或其他情況。在這種情況下，您可以簡單地做以下事情：

AkashicPay.getDepositAddress("TRX", "user1-normal");
// -> 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM'
AkashicPay.getDepositAddress("TRX", "user1-special");
// -> 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad'

或許您可以將此儲存於您的使用者，例如：

{
    userId: 'user1',
    wallets: [{address: 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM',
            identifier: 'user1-normal'},
             {address: 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad',
              identifier: 'user1-special'}]
}

像往常一樣，任何存入上述兩個地址的存款現在都會返回各自的識別碼 (identifier)。

這是一個展示如何使用 AkashicPay 的範例。但是，我們建議在用戶和存款地址之間始終保持一對一的映射，以獲得最高的效率和最小的混淆可能性。

Previous支援貨幣Next要求金額和貨幣 (Requested amount & currency)

Last updated

Was this helpful?