Sign in
भुगतान और निकासी/Payout API

Payout API

अपने merchant बैलेंस से किसी भी blockchain address पर निकासी भेजें।

Payout API आपको अपने merchant बैलेंस से किसी भी blockchain address पर programmatically फंड निकालने की सुविधा देता है।

सभी Payout endpoints के लिए, आपको sign सिग्नेचर generate करने के लिए एक अलग Payout API key का उपयोग करना होगा। यह key आपकी सामान्य API key से अलग है और इसे आपके project settings में generate किया जाना चाहिए।

निकासी बनाएँ

आपके merchant बैलेंस से निकासी request बनाता है।

POST/v1/payout

Request parameters

FieldTypeआवश्यकDescription
currencystringहाँनिकासी currency (देखें References)
networkstringहाँNetwork code (देखें References)
amountstringहाँनिकासी राशि
to_addressstringहाँप्राप्तकर्ता का blockchain address
order_idstringनहींIdempotency key — project के भीतर unique। समान order_id के साथ दोहराए गए POST से नया payout नहीं बनता — मौजूदा payout वापस लौटाया जाता है
url_callbackstringनहींpayout webhook के लिए URL। इस payout के लिए webhook बंद करने हेतु इसे न दें
memostring | nullनहींDestination tag / memo. वर्तमान में केवल TON और SOL networks द्वारा उपयोग किया जाता है; अधिकतम 255 chars
from_currencystringनहींSource बैलेंस जिसे payout के समय debit करके स्वतः ही currency में convert किया जाएगा। आप अपने बैलेंस को USDT जैसी stablecoin में रखते हुए volatile assets (BTC, ETH, …) में payout कर सकते हैं — आपको खुद volatile crypto रखने की जरूरत नहीं है। USDT बैलेंस से debit करने के लिए "USDT" pass करें
fee_optionstringनहींFees कैसे लगाए जाते हैं। deduct (default) — network + platform fees amount से घटाए जाते हैं, प्राप्तकर्ता को amount - fees मिलता है। add — fees ऊपर से जोड़े जाते हैं, merchant से amount + fees debit किया जाता है, प्राप्तकर्ता को ठीक amount मिलता है

Idempotency. Project के भीतर, एक payout order_id से unique होता है। समान order_id के साथ वही POST दोबारा भेजना सुरक्षित है — API duplicate बनाने के बजाय मौजूदा payout लौटाता है। Production payout के लिए हमेशा एक order_id pass करें।

Request examples

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

Response example

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

Fees. Default fee_option: deduct — network + platform fees amount से घटाए जाते हैं (प्राप्तकर्ता को amount - fees मिलता है)। ऊपर से fees लगाने के लिए fee_option: add pass करें — प्राप्तकर्ता को ठीक amount मिलता है और merchant से amount + fees debit किया जाता है।

Payout calculate करें

Payout बनाए बिना और balance debit किए बिना withdrawal amount और fees का estimate देता है। User को confirm करने से पहले उन्हें मिलने (या pay करने) वाली exact amount दिखाने के लिए इसका इस्तेमाल करें।

POST/v1/payout/calc

Request parameters

Create payout से identical — same fields, same signing। order_id, url_callback, to_address और memo accept तो होते हैं लेकिन ignore किए जाते हैं: कोई payout persist नहीं होता और कोई callback नहीं भेजा जाता।

Request example

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

Response example

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

Preview only. यह endpoint read-only है — कोई balance debit नहीं होता और कोई payout record नहीं बनता। UI में fee breakdown दिखाने के लिए जितनी बार जरूरत हो call कर सकते हैं।

Payout status

Payout request का status प्राप्त करें।

GET/v1/payout/status/{uuid}

Path parameters

FieldTypeआवश्यकDescription
uuidstringहाँPayout UUID (creation पर result.uuid से)

Response example

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

इस GET request के लिए सिग्नेचर खाली body से compute होता है: hash_hmac('sha256', base64_encode(''), $apiKey)

Response fields

POST /v1/payout और GET /v1/payout/status/{uuid} के result में लौटाए गए fields:

FieldTypeDescription
uuidstringसिस्टम द्वारा assigned Payout UUID
order_idstringआपका आंतरिक payout identifier (project के भीतर unique)
statusstringवर्तमान payout status (नीचे देखें)
currencystringनिकासी currency
networkstringNetwork code
amountstringrequested निकासी राशि
merchant_amountstringMerchant बैलेंस से debit की गई राशि
network_amountstringवास्तव में on-chain भेजी गई राशि (network + platform fees के बाद)
amount_usdstringनिकासी राशि का USD equivalent
to_addressstringप्राप्तकर्ता का blockchain address
memostring | nullDestination tag / memo (TON, SOL)। अन्यथा null
txidstring | nullBlockchain transaction hash. transaction भेजे जाने तक null
block_numberint | nullBlock number जहाँ transaction included था। शामिल होने तक null
error_typestring | nullstatus = failed होने पर failure का कारण (नीचे Error types देखें)। अन्यथा null
created_atstring (ISO 8601)Payout creation का समय
updated_atstring (ISO 8601)अंतिम status परिवर्तन का समय
from_currencystring | nullAuto-conversion का उपयोग होने पर वह source बैलेंस जिससे payout debit हुआ था (जैसे BTC payout के लिए USDT)। यदि कोई conversion नहीं हुआ तो null
debited_amountstring | nullConversion के बाद source बैलेंस से वास्तव में debit की गई राशि। केवल auto-conversion के उपयोग पर उपस्थित
debited_currencystring | nulldebited_amount की currency — वह बैलेंस जहाँ से फंड debit किए गए

Payout statuses

status field निम्न values ले सकता है:

StatusDescription
pendingबनाया गया, processing की प्रतीक्षा में
completedसफलतापूर्वक पूर्ण — txid set है
failedभेजने में त्रुटि — error_type देखें
cancelledरद्द कर दिया गया

Error types

जब status = failed होता है, तो error_type field कारण बताता है:

CodeDescription
aml_riskAML risk checks द्वारा payout block (प्राप्तकर्ता address को high-risk के रूप में flag किया गया)

Webhook notifications

जब किसी payout का status बदलता है, तो सिस्टम payout बनाते समय pass किए गए url_callback URL पर एक POST webhook भेजता है। यदि url_callback प्रदान नहीं किया गया था, तो उस payout के लिए कोई webhook नहीं भेजा जाता।

  • Method: POST
  • Content-Type: application/json
  • Signature: request body में sign field, Payout API key के साथ compute किया गया (वही key जो payout request को sign करने के लिए उपयोग की जाती है)।

Payload GET /v1/payout/status/{uuid} के result object को mirror करता है, साथ में verification के लिए एक sign field होता है।

Payload

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

सिग्नेचर verify करना. payment webhooks के लिए वही algorithm उपयोग करें, लेकिन सामान्य API key के बजाय अपनी Payout API key से sign करें। sign field हटा दें, बाकी payload को JSON-encode करें, Base64-encode करें, फिर hash_hmac('sha256', $base64, $payoutApiKey) compute करें और प्राप्त sign से तुलना करें।