Convert API

Convert API memungkinkan Anda menukar antar mata uang yang disimpan di saldo merchant Anda dengan harga pasar saat ini — mesin yang sama yang menggerakkan tab Swap di dashboard merchant, kini dapat dipanggil dari backend Anda.

Mendapatkan harga konversi

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Menjalankan konversi

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Error

Saat gagal, respons memiliki state: 1 dan sebuah error_code — bersama untuk /v1/convert/price dan /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Konversi otomatis untuk pembayaran masuk

Konversi otomatis adalah pengaturan proyek untuk faktur masuk dan kredit dompet statis. Ini dikonfigurasi di dasbor pedagang, bukan dengan menambahkan bidang ke /v1/payment. Setiap aturan memilih satu atau lebih mata uang sumber dan satu mata uang target.

Saat konversi selesai, info pembayaran dan webhook pedagang dapat mencakup:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Domain jumlah sengaja dipisahkan:

• payment_amount — apa yang terdeteksi di blockchain dalam mata uang pembayaran sumber;
• merchant_amount — jumlah sumber bersih yang menjadi hak pedagang sebelum konversi;
• convert.amount — jumlah yang dikreditkan dalam convert.to_currency;
• convert.rate dan convert.commission — hasil konversi yang dijalankan, bukan harga yang harus Anda hitung ulang secara lokal.

Kegagalan dan fallback konversi otomatis

Konversi berada di hilir menerima pembayaran blockchain. Ketersediaan pasar, ukuran pesanan minimum, batas presisi, waktu habis pertukaran, dan likuiditas yang tidak cukup dapat menunda atau mencegah konversi.

• Setoran di bawah minimum global/proyek melewati jalur konversi dan mengkredit mata uang sumber.
• Kegagalan sementara dapat dicoba kembali secara asinkron.
• Setoran besar atau yang tidak dapat diperdagangkan dapat kembali ke kredit dalam mata uang sumber setelah kebijakan percobaan ulang habis.
• Oleh karena itu, sebuah pembayaran dapat tetap berlaku meskipun konversi ke mata uang target yang diinginkan tidak terjadi.

Integrasi Anda harus menyimpan pembayaran yang telah diverifikasi terlebih dahulu, kemudian mencocokkan mata uang yang sebenarnya dikreditkan dari info pembayaran, blok opsional convert, dan saldo pedagang. Jangan menahan pengakuan webhook pembayaran sambil menunggu sistem analitik atau notifikasi Anda sendiri.

Uji penerimaan konversi otomatis

Uji setidaknya: konversi langsung yang berhasil, konversi jembatan/multi-langkah, debu di bawah minimum, percobaan ulang sementara, fallback ke mata uang sumber, pembayaran kurang, pembayaran berlebih, webhook duplikat, convert hilang, dan rekonsiliasi setelah timeout ambigu.

Kasus tepi konversi manual

• /v1/convert/price adalah pratinjau indikatif; pergerakan pasar dapat mengubah hasil eksekusi.
• amount_type: from memperbaiki permintaan sisi sumber, sementara amount_type: to meminta jumlah sisi target. Jangan menukar maknanya saat menampilkan UI konfirmasi.
• Pasangan tanpa pasar langsung dapat dialihkan melalui mata uang perantara. Jika hanya satu kaki yang selesai, partially_completed melaporkan kredit perantara.
• Jika panggilan eksekusi mengalami timeout, lakukan rekonsiliasi sebelum mencoba lagi. Pesanan pasar dapat dieksekusi meskipun respons HTTP-nya hilang.
• Perlakukan failed sebagai status untuk direkonsiliasi, bukan sebagai izin untuk menerapkan entri saldo kompensasi lokal; platform memiliki akuntansi debit/refund.