# 提款/提幣 (payout)

* 確保地址格式正確，並符合網路。
* 金額必須是字串 (string)，並應使用標準貨幣單位。例如：ETH (而非 WEI) 和 TRX (而非 SUN)
* 代幣是可選的，僅在發送令牌時使用。例如：USDT

## <mark style="color:blue;">範例</mark>

在 Tron 上為 `user123` 傳送 100 USDT 到 `TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const { l2Hash } = await akashicPay.payout(
  "user123",
  "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU",
  "100",
  NetworkSymbol.Tron,
  TokenSymbol.USDT
);
```

{% endtab %}

{% tab title="PHP" %}

```php
$result = $akashicPay->payout(
  "user123",
  "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU",
  "100",
  NetworkSymbol::TRON,
  TokenSymbol::USDT
);
```

{% endtab %}

{% tab title="Java" %}

```java
APPayoutResult result = akashicPay.payout(
  "user123",
  "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU",
  100.0,
  APNetworkSymbol.TRX,
  APTokenSymbol.USDT
);
```

{% endtab %}

{% tab title="C#" %}

```csharp
var trxPayoutResult = await sdk.PayoutAsync(
  "user123",
  "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU",
  "100",
  TronShastaNetworkSymbol.Value,
  ApTokenSymbol.Usdt
);
```

{% endtab %}

{% tab title="Go" %}

```go
l2Hash, err := ap.Payout("user123", "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU", "100", akashicpay.Tron, akashicpay.USDT)

```

{% endtab %}
{% endtabs %}

## <mark style="color:blue;">回調範例</mark>

如果交易成功，則返回 [L2](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#di-er-ceng-layer2) 交易哈希值。否則返回錯誤代碼。

注意: `l2Txnhash` (「L2-hash」) 應該永遠用作交易的唯一識別碼 (identifier)。這是 [AkashicChain](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#akashicchain) 上任何交易的唯一交易哈希值 (transaction-hash)。它存在於已確認的存款和待定/已確認的付款中。這對於[第二層](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#di-er-ceng-layer2)交易尤其重要，因為第二層交易沒有第一層哈希值 (<kbd>txHash</kbd>)

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Success
{
  l2Hash: "ASe5659e1700b9004ef06a622e49b6d367d3a76d3fed5e7872aaf684b51b824a89";
}

// Failure
{
  error: AkashicErrorCode.SavingsExceeded; // 'FUNDS_EXCEEDED'
}
```

{% endtab %}

{% tab title="PHP" %}

```php
["l2Hash" => 'ASe5659e1700b9004ef06a622e49b6d367d3a76d3fed5e7872aaf684b51b824a89']
```

{% endtab %}

{% tab title="Java" %}

```java
{
  l2Hash: "ASe5659e1700b9004ef06a622e49b6d367d3a76d3fed5e7872aaf684b51b824a89"
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
{
  l2Hash: "ASe5659e1700b9004ef06a622e49b6d367d3a76d3fed5e7872aaf684b51b824a89"
}
```

{% endtab %}

{% tab title="Go" %}

```go
// L2 Hash (string)
"ASe5659e1700b9004ef06a622e49b6d367d3a76d3fed5e7872aaf684b51b824a89"
```

{% endtab %}
{% endtabs %}

## <mark style="color:blue;">錯誤訊息</mark>

在任何預期的失敗情況下，函式 (function) 將回調一個帶有錯誤代碼的欄位名稱 `error`。請注意，任何意料之外的失敗（如網路問題導致交易提交超時）仍可能產生錯誤。如需所有錯誤的完整清單，請參閱[錯誤訊息(Errors)](https://docs.akashicpay.com/traditional-chinese/sdk/cuo-wu-xun-xi-errors)。

\* 在 `Go` 的情況下，會根據標準 Go 慣例傳回錯誤物件。

函式 (functions) 回調的預期錯誤有：

<table><thead><tr><th>錯誤</th><th>解釋</th></tr></thead><tbody><tr><td><pre><code>L2ADDRESS_NOT_FOUND
</code></pre></td><td>如果嘗試傳送至第二層交易，而收件人不存在於AkashicChain上。如果只進行<a href="../../../jian-jie/shu-yu#di-yi-ceng-layer1">第一層</a>交易，請忽略此項。<br></td></tr><tr><td><pre><code>FUNDS_EXCEEDED
</code></pre></td><td>您沒有足夠的資金完成交易。請重新檢查您的餘額。</td></tr><tr><td><pre><code>UNKNOWN_ERROR
</code></pre></td><td>通常表示您做錯了什麼。例如，在未向 AkashicPay 建立或加入帳號的情況下嘗試發送。也可能表示 AkashicPay 在嘗試協調交易時發生了意料之外的問題。這種情況應該很少發生。檢查您的詳細資料，快速重試，如果找不到解決方案，請聯絡客戶服務。</td></tr></tbody></table>

如果產生 `UNKNOWN_ERROR`，可能表示 [AkashicChain](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#akashicchain) 出錯。請檢查所拋出錯誤的詳細資訊 (`details`)，以瞭解更多資訊 。如果您沒有出錯，這些錯誤通常都是短暫的，延遲一小段時間後再重試應該就會成功。

## <mark style="color:blue;">回調</mark>

如果在Akashicpay.com上註冊了支付的回調 URL，您將收到一個 HTTP 呼叫到該 URL，正文如下：

注意：如果對回調的回應狀態代碼 (status code) >= 400，則回調最多會重試 10 次，延遲時間從第一次嘗試開始計算，最多可延遲 15 分鐘左右。

> 注意：雖然我們的目標是在 Akashic 的穩定性和一致性，我們不能保證下面的對象保持不變。舉例來說，新的功能可能需要在回調中加入額外的欄位。然而，我們的目標是不移除現有的欄位。為了方便起見，我們建議根據您的需求過濾和處理回調，同時對未來新增的可能性持開放態度。

```json
  {
  "fromAddress": "TTVkK6hGoAFhALG9NTkUDHjcFFXKmWcScU", // sending wallet/account of transaction
  "toAddress": "TQH8ygbS8BAnzSQ9uxR9vXHJYMQVRvbgPg", // receiving wallet/account of transaction
  "layer": "L1Transaction", // 'L1Transaction' or 'L2Transaction'
  "initiatedAt": "2024-08-19T10:02:54.000Z", // ISO8601 format
  "confirmedAt": "2024-08-19T10:04:02.000Z", // Only present if status is 'Confirmed' or 'Failed'
  "amount": "1.000000",  // Amount sent
  "coinSymbol": "TRX", // NetworkSymbol, e.g. 'ETH' or 'TRX'
  "status": "Confirmed", // TransactionStatus. 'Pending', 'Confirmed', or 'Failed'
  "txHash": "28a9880ad2ef3b7be1c40763128ec9630ab74e4749a3c81037c3501e4209bfcc", // Network's hash if L1. Not present for L2
  "feesEstimate": "6.114654", // Gas fee estimated by Akashic. Not present for L2
  "feesPaid": "5.822220, // Gas Fee paid on network. Not present for L2
  "l2TxnHash": "ASe7eb1cb8193787040fcffa02a224a6ced7415ff2205343c0ab661e898e8d6eef", // Akashic Transaction Hash. For both L1 and L2 
  "senderInfo": {
    "identity": "ASbb8efead2d5ff2f618a85895bac8e8ac1bae236d4d730bf113400b7e6f108ca5", // Akashic Address of sender
  },
  "senderIdentity": "ASbb...", // DEPRECATED. Same as above. Please use senderInfo.identity instead
  "tokenSymbol": "USDT", // TokenSymbol. Present only if token-transaction
  "internalFee": {
    "withdraw": "0.100000"
  }, // Akashic Fee { deposit?: string, withdraw?: string}
   "identifier": "user123", // User-identifier
   "feeIsDelegated": false, // Whether L1 gas fees were paid using token instead of native coin
   "directResolution": false // true if the transaction was never registered in the "Pending" state
}

```

#### *關於提款費用的說明*

提款時，有幾種不同的費用。這些是：

* Akashic 費用 (回調中的 `internalFee.withdraw`)，總是與交易貨幣相同。例如，**ETH 轉帳用 ETH，USDT 轉帳用 USDT，USDC 轉帳用 USDC，等等。除非發生「費用代付」，否則通常為 0，請參閱下文。**
* [礦工費](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#fei-yong-kuang-gong-fei) (回調中的 `feesPaid`)，總是以[原生幣](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#huo-bi)計算 (例如 ETH 代表 ERC20 USDT 或 USDC 轉帳，TRX 代表 TRC20 USDT 轉帳，BNB 代表 BEP20 USDT 或 USDC 轉帳等)。由 [L1 網路](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#di-yi-ceng-layer1)收取 (以太坊 (Ethereum)、波場 (Tron) 等。)
* 「費用代付」。Akashic 系統讓您用代幣而非原生幣來支付上述的原生費用，以簡化問題。如果這樣做，`feeIsDelegated` 將會在回調中為 `true`。所有使用 SDK 完成的提款都應該是 「代付」的，而從 [AkashicLink](https://docs.akashicpay.com/traditional-chinese/jian-jie/shu-yu#akashiclink) 啟動的提款預設不會是 「代付」的。「代付」費用所需的額外代幣金額在 `internalFee.withdraw` 中。

利用這一點，我們可以計算使用者花費的總金額（假設上圖所示的回調資料在 `txCallback` 中）：

```typescript
// Token transaction (USDT)
if (txCallback.tokenSymbol) {
    userTokenSpent = txCallback.amount + txCallback.internalFee.withdraw;
    // If fee is not delegated, gas fees are paid in native coin
    if (!feeIsDelegated) {
        userNativeCoinSpent = txCallback.feesPaid;
    }
} else {
// Coin transaction (ETH, TRX)
    userNativeCoinSpent = txCallback.amount + txCallback.internalFee.withdraw 
        + txCallback.feesPaid;
}

```

請注意，以上是偽碼 (pseudocode)。您可能需要額外注意處理潛在的未定義/空值（如 `internalFee`），並根據您所選程式語言的一般慣例，安全正確地解析數字。