Sign in
Pembayaran dan penarikan/Payout API

Payout API

Kirim penarikan dari saldo merchant Anda ke alamat blockchain mana pun.

Payout API memungkinkan Anda menarik dana secara terprogram dari saldo merchant Anda ke alamat blockchain mana pun.

Untuk semua endpoint Payout, Anda harus menggunakan Payout API key terpisah untuk menghasilkan tanda tangan sign. Key ini berbeda dari API key biasa Anda dan harus dibuat di pengaturan project.

Buat penarikan

Membuat permintaan penarikan dari saldo merchant Anda.

POST/v1/payout

Parameter permintaan

FieldTipeWajibDeskripsi
currencystringyaMata uang penarikan (lihat References)
networkstringyaKode jaringan (lihat References)
amountstringyaJumlah penarikan
to_addressstringyaAlamat blockchain penerima
order_idstringtidakKunci idempotensi — unik dalam satu project. POST berulang dengan order_id yang sama tidak akan membuat penarikan baru — yang sudah ada akan dikembalikan
url_callbackstringtidakURL untuk webhook penarikan. Hilangkan untuk menonaktifkan webhook untuk penarikan ini
memostring | nulltidakDestination tag / memo. Saat ini hanya digunakan oleh jaringan TON dan SOL; maks 255 karakter
from_currencystringtidakSaldo sumber yang akan didebet dan dikonversi otomatis ke currency pada saat penarikan. Memungkinkan Anda menarik dalam aset volatil (BTC, ETH, …) sambil menyimpan saldo dalam stablecoin seperti USDT — Anda tidak perlu memegang sendiri kripto volatil tersebut. Berikan "USDT" untuk mendebet saldo USDT
fee_optionstringtidakCara biaya dibebankan. deduct (default) — biaya jaringan + platform dikurangi dari amount, penerima mendapat amount - fees. add — biaya ditambahkan di atas, merchant didebit amount + fees, penerima menerima tepat amount

Idempotensi. Dalam satu project, sebuah penarikan unik berdasarkan order_id. Mengirim ulang POST yang sama dengan order_id yang sama aman — API mengembalikan penarikan yang sudah ada alih-alih membuat duplikat. Selalu berikan order_id untuk penarikan produksi.

Contoh permintaan

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"}'

Contoh respon

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"
  }
}

Biaya. Default fee_option: deduct — biaya jaringan + platform dikurangi dari amount (penerima mendapat amount - fees). Berikan fee_option: add untuk membebankan biaya di atas — penerima mendapat tepat amount dan merchant didebit amount + fees.

Hitung penarikan

Menghitung estimasi jumlah dan biaya penarikan tanpa membuat penarikan dan tanpa mendebit saldo Anda. Gunakan untuk menampilkan kepada pengguna jumlah tepat yang akan diterima (atau dibayar) sebelum konfirmasi.

POST/v1/payout/calc

Parameter permintaan

Identik dengan Buat penarikan — field yang sama, penandatanganan yang sama. order_id, url_callback, to_address, dan memo diterima namun diabaikan: tidak ada penarikan yang disimpan dan tidak ada callback yang dikirim.

Contoh permintaan

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"}'

Contoh respon

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"
  }
}

Hanya pratinjau. Endpoint ini hanya-baca — tidak ada saldo yang didebit dan tidak ada rekam penarikan yang dibuat. Panggil sesering yang Anda perlukan untuk merender rincian biaya di UI Anda.

Status penarikan

Dapatkan status sebuah permintaan penarikan.

GET/v1/payout/status/{uuid}

Parameter path

FieldTipeWajibDeskripsi
uuidstringyaUUID penarikan (dari result.uuid saat pembuatan)

Contoh respon

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"
  }
}

Untuk permintaan GET ini, tanda tangan dihitung dari body kosong: hash_hmac('sha256', base64_encode(''), $apiKey)

Field respon

Field yang dikembalikan di result dari POST /v1/payout dan GET /v1/payout/status/{uuid}:

FieldTipeDeskripsi
uuidstringUUID penarikan yang ditetapkan oleh sistem
order_idstringPengenal penarikan internal Anda (unik dalam project)
statusstringStatus penarikan saat ini (lihat di bawah)
currencystringMata uang penarikan
networkstringKode jaringan
amountstringJumlah penarikan sesuai permintaan
merchant_amountstringJumlah yang didebit dari saldo merchant
network_amountstringJumlah yang sebenarnya dikirim on-chain (setelah biaya jaringan + platform)
amount_usdstringEkuivalen USD dari jumlah penarikan
to_addressstringAlamat blockchain penerima
memostring | nullDestination tag / memo (TON, SOL). null jika tidak ada
txidstring | nullHash transaksi blockchain. null hingga transaksi dikirim
block_numberint | nullNomor blok tempat transaksi disertakan. null hingga disertakan
error_typestring | nullAlasan kegagalan saat status = failed (lihat Tipe error di bawah). null jika tidak ada
created_atstring (ISO 8601)Waktu pembuatan penarikan
updated_atstring (ISO 8601)Waktu perubahan status terakhir
from_currencystring | nullSaldo sumber yang didebet untuk penarikan ketika konversi otomatis digunakan (mis. USDT untuk penarikan BTC). null jika tidak ada konversi
debited_amountstring | nullJumlah yang sebenarnya didebit dari saldo sumber setelah konversi. Hadir hanya saat konversi otomatis digunakan
debited_currencystring | nullMata uang dari debited_amount — saldo dari mana dana didebit

Status penarikan

Field status dapat berisi nilai berikut:

StatusDeskripsi
pendingDibuat, menunggu pemrosesan
completedSelesai dengan sukses — txid telah ditetapkan
failedKesalahan pengiriman — lihat error_type
cancelledDibatalkan

Tipe error

Saat status = failed, field error_type menjelaskan alasannya:

KodeDeskripsi
aml_riskPenarikan diblokir oleh pemeriksaan risiko AML (alamat penerima ditandai berisiko tinggi)

Notifikasi webhook

Saat status sebuah penarikan berubah, sistem mengirim webhook POST ke URL url_callback yang diteruskan saat penarikan dibuat. Jika url_callback tidak disediakan, tidak ada webhook yang dikirim untuk penarikan tersebut.

  • Method: POST
  • Content-Type: application/json
  • Tanda tangan: field sign di body permintaan, dihitung dengan Payout API key (key yang sama digunakan untuk menandatangani permintaan penarikan).

Payload mencerminkan objek result dari GET /v1/payout/status/{uuid} plus field sign untuk verifikasi.

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"
}

Memverifikasi tanda tangan. Gunakan algoritma yang sama seperti untuk webhook pembayaran, tetapi tandatangani dengan Payout API key Anda alih-alih API key biasa. Hapus field sign, encode payload tersisa ke JSON, encode ke Base64, lalu hitung hash_hmac('sha256', $base64, $payoutApiKey) dan bandingkan dengan sign yang diterima.