Dokumentasi API Pembayaran

Mulai cepat

Tiga langkah sampai pembayaran pertama Anda terbentuk.

1. Daftar dan terbitkan kunci sandbox dari halaman ringkasan.
2. Kirim permintaan pembuatan pembayaran seperti contoh di bawah.
3. Daftarkan alamat notifikasi agar sistem Anda tahu ketika pelanggan sudah membayar.

curl -X POST http://localhost:3040/api/v1/payments \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Idempotency-Key: PESANAN-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "PESANAN-0001",
    "amount": 150000,
    "method": { "type": "VIRTUAL_ACCOUNT", "channel": "BNI" }
  }'

Pendaftaran lewat API

Bila Anda memasang layanan ini di dalam produk Anda sendiri, merchant dapat didaftarkan langsung dari peladen Anda tanpa membuka halaman web. Kunci API sandbox diterbitkan pada jawaban yang sama, sehingga integrasi dapat berjalan seketika.

curl -X POST https://api.langsunggas.shop/api/v1/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@usaha-anda.com",
    "password": "kata-sandi-minimal-12",
    "legal_name": "PT Usaha Anda Sejahtera",
    "display_name": "Usaha Anda",
    "scopes": ["payments:write", "payments:read", "payouts:read"]
  }'

Jawaban berstatus 201.

{
  "merchant": {
    "id": "mch_xxxxxxxxxxxx",
    "legal_name": "PT Usaha Anda Sejahtera",
    "display_name": "Usaha Anda",
    "status": "ACTIVE_SANDBOX"
  },
  "api_key": {
    "id": "key_xxxxxxxxxxxx",
    "prefix": "a1b2c3d4e5f6",
    "secret": "lg_sandbox_a1b2c3d4e5f6_xxxxxxxxxxxxxxxxxxxx",
    "environment": "SANDBOX",
    "scopes": ["payments:write", "payments:read"],
    "grantable_scopes": [
      "payments:write",
      "payments:read",
      "payouts:read",
      "crypto-withdrawals:read"
    ]
  },
  "next_steps": [
    "Simpan nilai api_key.secret sekarang. Nilai itu tidak dapat dibaca kembali.",
    "Panggil GET /api/v1/channels untuk melihat kanal pembayaran yang tersedia.",
    "Kirim berkas kelayakan usaha lewat POST /api/v1/kyb sebelum memakai mode live.",
    "Izin menulis pencairan dan penarikan kripto dibuka operator bersamaan dengan kenaikan ke mode live."
  ],
  "request_id": "req_xxxxxxxx"
}

Bila operator memasang kunci penjaga, sertakan tajuk X-Signup-Secret. Tanpa tajuk itu jawabannya 401 UNAUTHORIZED.

Kunci pertama membawa izin pembayaran saja bila kolom scopes dikosongkan. Sertakan kolom itu untuk meminta izin membaca pencairan atau penarikan kripto, sehingga integrasi Anda dapat disiapkan lebih dahulu.

Autentikasi

Setiap permintaan menyertakan kunci pada tajuk Authorization.

Authorization: Bearer lg_sandbox_a1b2c3d4_xxxxxxxxxxxxxxxx
Idempotency-Key: PESANAN-0001
Content-Type: application/json

Setiap kunci membawa daftar izin. Permintaan di luar izin kunci dijawab 403 FORBIDDEN.

Mengelola kunci lewat API

Kunci dapat didaftar, diterbitkan, dan dicabut tanpa membuka halaman web. Wewenangnya berasal dari kunci yang Anda pakai memanggil, sehingga seluruh daur hidup kunci dapat dijalankan dari peladen Anda sendiri.

Mengembalikan kunci pada lingkungan yang sama dengan kunci pemanggil. Hanya metadata; rahasia tidak pernah dapat dibaca ulang. Baris dengan current: true adalah kunci yang sedang Anda pakai.

curl https://api.langsunggas.shop/api/v1/api-keys \
  -H "Authorization: Bearer lg_sandbox_kunci_anda"

{
  "environment": "SANDBOX",
  "active_limit": 10,
  "active_count": 2,
  "data": [
    {
      "id": "key_xxxxxxxxxxxx",
      "prefix": "1ff77c9739cc",
      "environment": "SANDBOX",
      "scopes": ["payments:write", "payments:read"],
      "current": true,
      "status": "ACTIVE",
      "created_at": "2026-10-10T09:59:44.980Z",
      "last_used_at": "2026-10-10T09:59:45.623Z",
      "revoked_at": null
    }
  ]
}

Menerbitkan kunci baru. Kolom scopes boleh dikosongkan untuk menyalin izin kunci pemanggil. Lingkungan tidak dapat diminta, selalu mengikuti kunci pemanggil.

curl -X POST https://api.langsunggas.shop/api/v1/api-keys \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["payments:read"] }'

Pola yang disarankan adalah menerbitkan kunci sesempit mungkin untuk setiap pemakaian. Kunci yang hanya membaca status pembayaran cukup berizin payments:read, sehingga kebocorannya tidak dapat dipakai membuat tagihan.

Mencabut kunci. Id dapat dikirim lewat kueri ?api_key_id= atau badan JSON. Pencabutan bersifat idempoten; mengulanginya dijawab 200 dengan already_revoked: true.

curl -X DELETE \
  "https://api.langsunggas.shop/api/v1/api-keys?api_key_id=key_xxxxxxxxxxxx" \
  -H "Authorization: Bearer lg_sandbox_kunci_anda"

{
  "id": "key_xxxxxxxxxxxx",
  "prefix": "1ff77c9739cc",
  "status": "REVOKED",
  "already_revoked": false,
  "self_revoked": false,
  "request_id": "req_xxxxxxxx"
}

Kolom environment menentukan lingkungan kunci baru. Dikosongkan berarti menyalin lingkungan kunci pemanggil. Inilah cara memperoleh kunci sungguhan tanpa membuka dasbor: kunci pertama Anda selalu lahir sebagai kunci uji, sehingga tanpa kolom ini mode langsung tidak akan pernah terjangkau.

Aturan izin tetap berlaku terpisah dari lingkungan: kunci baru tidak pernah boleh melampaui izin pemanggilnya, sehingga kunci sungguhan yang Anda terbitkan sendiri paling banyak memegang izin yang sudah Anda miliki. Untuk menambah izin menulis pencairan, hubungi operator.

Keterangan akun

Memeriksa keadaan akun Anda sendiri beserta izin kunci yang sedang dipakai. Berguna bagi integrasi yang berjalan tanpa membuka dasbor, karena tiga hal pada jawaban ini menentukan perilaku yang benar: lingkungan yang boleh dipakai, cara pencairan diproses, dan tarif yang dikenakan.

curl https://api.langsunggas.shop/api/v1/me \
  -H "Authorization: Bearer lg_sandbox_kunci_anda"

{
  "merchant": {
    "id": "mch_xxxxxxxxxxxx",
    "legal_name": "PT Usaha Anda Sejahtera",
    "display_name": "Usaha Anda",
    "status": "ACTIVE_SANDBOX",
    "country_code": "ID",
    "created_at": "2026-10-10T10:31:21.302Z",
    "suspended_at": null,
    "suspended_reason": null,
    "kyb_status": "PENDING",
    "live_enabled": false,
    "allowed_environments": ["SANDBOX"],
    "disbursement_mode": "MANUAL"
  },
  "api_key": {
    "id": "key_xxxxxxxxxxxx",
    "environment": "SANDBOX",
    "scopes": ["payments:write", "payments:read"]
  },
  "fees": {
    "plan": "Tarif Umum v1",
    "rules": [
      { "payment_method": "VIRTUAL_ACCOUNT", "calc_type": "FLAT", "flat_amount": 4000, "percentage_bps": 0 },
      { "payment_method": "QRIS", "calc_type": "PERCENTAGE", "flat_amount": 0, "percentage_bps": 70 }
    ]
  }
}

Endpoint ini tidak menuntut izin khusus, karena mengetahui keadaan akun sendiri adalah hak setiap pemegang kunci yang sah dan tidak ada angka dana yang disertakan. Untuk saldo, pakai GET /api/v1/balance.

Kelayakan usaha (KYB)

Kunci yang terbit dari pendaftaran lewat API selalu berlingkungan uji. Agar akun dapat memproses dana sungguhan, data kelayakan usaha harus dikirim dan ditinjau lebih dahulu. Kedua endpoint ini membuat seluruh langkahnya dapat ditempuh tanpa membuka dasbor.

Berkas kelayakan mengikat badan usaha, bukan lingkungan, sehingga kunci uji pun dapat memakainya. Memang justru merchant yang masih di lingkungan uji yang membutuhkannya.

curl https://api.langsunggas.shop/api/v1/kyb \
  -H "Authorization: Bearer lg_sandbox_kunci_anda"

{
  "status": "PENDING",
  "next_step": "SUBMIT_DOCUMENTS",
  "can_submit": true,
  "merchant_status": "ACTIVE_SANDBOX",
  "live_enabled": false,
  "submitted_at": null,
  "reviewed_at": null,
  "rejection_reason": null,
  "business": {
    "business_type": null,
    "registration_number": null,
    "tax_number": null,
    "website_url": null,
    "contact_phone": null,
    "business_address": null,
    "document_urls": []
  }
}

Bacalah next_step dan ikuti nilainya, jangan menyimpulkan sendiri dari status. Pemetaan status ke tindakan adalah aturan kami dan dapat berkembang, sedangkan nilai pada kolom ini akan tetap menunjuk tindakan yang benar.

curl -X POST https://api.langsunggas.shop/api/v1/kyb \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{
    "business_type": "Perdagangan daring",
    "registration_number": "AHU-0012345-AH-01-01",
    "tax_number": "01.234.567.8-901.000",
    "website_url": "https://usahaanda.co.id",
    "contact_phone": "081200001111",
    "business_address": "Jalan Merdeka Nomor 10, Jakarta Selatan, DKI Jakarta",
    "document_urls": [
      "https://berkas.usahaanda.co.id/akta.pdf",
      "https://berkas.usahaanda.co.id/npwp.pdf"
    ]
  }'

{
  "status": "IN_REVIEW",
  "next_step": "WAIT_REVIEW",
  "message": "Berkas dikirim dan menunggu peninjauan operator."
}

Kanal pembayaran

Daftar kanal yang benar-benar dapat Anda pakai, sudah dikelompokkan dan mengikuti lingkungan kunci yang dipakai. Gunakan ini untuk menyusun pilihan pembayaran, agar Anda tidak menawarkan kanal yang akan ditolak saat tagihan dibuat.

curl https://api.langsunggas.example/api/v1/channels \
  -H "Authorization: Bearer lg_sk_test_xxxxxxxx"

{
  "environment": "SANDBOX",
  "total": 9,
  "data": [
    {
      "group": "VIRTUAL_ACCOUNT",
      "group_name": "Virtual Account",
      "channels": [
        {
          "code": "BNI",
          "name": "Bank BNI",
          "method_type": "VIRTUAL_ACCOUNT",
          "description": "Virtual account nominal terkunci",
          "available": true
        }
      ]
    },
    {
      "group": "QR",
      "group_name": "QRIS",
      "channels": [
        {
          "code": "QRIS",
          "name": "QRIS",
          "method_type": "QRIS",
          "description": "Pindai kode dari aplikasi apa pun yang mendukung QRIS",
          "available": true
        }
      ]
    }
  ]
}

Kolom code adalah nilai yang Anda kirim padamethod.channel, sedangkan method_typeadalah nilai untuk method.type. Khusus kelompokCRYPTO, keduanya bernilai sama danmethod.channel tidak perlu dikirim.

Pada mode tersebut, setiap kanal membawa available danblocked_reason.

Menyalakan dan mematikan kanal

Mengubah kanal yang Anda tawarkan tanpa membuka dasbor. Lingkungan tidak pernah diminta, selalu diambil dari kunci, sehingga kanal produksi tidak dapat diubah memakai kunci uji.

curl -X PATCH https://api.langsunggas.shop/api/v1/channels \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "BNI", "enabled": false }'

{
  "channel": "BNI",
  "enabled": false,
  "environment": "SANDBOX"
}

Membuat pembayaran

Virtual Account:

{
  "reference_id": "PESANAN-2026-0001",
  "amount": 275000,
  "method": { "type": "VIRTUAL_ACCOUNT", "channel": "BNI" },
  "customer": { "name": "Budi Santoso" }
}

QRIS:

{
  "reference_id": "PESANAN-2026-0002",
  "amount": 45000,
  "method": { "type": "QRIS" }
}

Jawaban berhasil dengan kode 201:

{
  "id": "pay_xxxxxxxxxxxx",
  "reference_id": "PESANAN-2026-0001",
  "status": "PENDING",
  "amount": 275000,
  "currency": "IDR",
  "method": {
    "type": "VIRTUAL_ACCOUNT",
    "channel": "BNI",
    "accountNumber": "8808999979278987",
    "accountName": "XDT-InoPay"
  },
  "expires_at": "2026-08-21T03:59:21.317Z",
  "created_at": "2026-08-21T02:59:21.631Z"
}

Idempotensi

Tajuk Idempotency-Key wajib disertakan pada setiap pembuatan pembayaran. Tajuk ini mencegah tagihan ganda ketika jaringan bermasalah dan permintaan yang sama terkirim dua kali.

Membaca pembayaran

Daftar memakai penomoran berbasis kursor. Sertakan nilainext_cursor dari jawaban sebelumnya untuk mengambil halaman berikutnya.

{
  "data": [
    {
      "id": "pay_xxxxxxxxxxxx",
      "status": "PAID",
      "amount": 275000,
      "paid_at": "2026-08-21T03:01:04Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cmt2xxxxxxxxxx"
}

Biaya layanan

Setiap pembayaran yang lunas dikenai biaya layanan. Nominal yang masuk ke dompet Anda adalah nominal yang dibayar pelanggan dikurangi biaya tersebut, bukan nominal penuh.

Besaran biaya ditetapkan operator dan dapat berbeda antar merchant sesuai kesepakatan. Tarif yang berlaku bagi akun Anda dapat ditanyakan kepada operator.

Karena itu, jangan menghitung penerimaan dari nominal tagihan. Pakai saldo pada halaman Dompet atau catatan mutasi, yang sudah memperhitungkan potongan.

Saldo dan mutasi dompet

Saldo dan mutasi dapat dibaca langsung dari peladen Anda untuk keperluan rekonsiliasi, tanpa membuka dasbor.

curl https://api.langsunggas.shop/api/v1/balance \
  -H "Authorization: Bearer lg_live_kunci_anda"

{
  "environment": "LIVE",
  "idr": {
    "currency": "IDR",
    "available": 542000,
    "pending": 0,
    "total": 542000,
    "minimum_payout": 10000
  },
  "usdt": {
    "currency": "USDT",
    "available": 0,
    "available_display": "0",
    "decimals": 6
  }
}

Mutasi dompet rupiah, terbaru lebih dahulu. Parameter limit paling banyak 100 dengan bawaan 30, dan offset dipakai untuk melanjutkan ke halaman berikutnya selama has_more masih benar.

curl \
  "https://api.langsunggas.shop/api/v1/wallet-entries?limit=20&offset=0" \
  -H "Authorization: Bearer lg_live_kunci_anda"

{
  "environment": "LIVE",
  "currency": "IDR",
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "data": [
    {
      "occurred_at": "2026-10-10T10:24:06.514Z",
      "description": "Pembayaran diterima",
      "direction": "CREDIT",
      "amount": 346000,
      "reference_id": "PESANAN-2026-0001"
    },
    {
      "occurred_at": "2026-10-09T08:11:02.003Z",
      "description": "Pencairan selesai",
      "direction": "DEBIT",
      "amount": 500000,
      "reference_id": null
    }
  ]
}

Nilai direction dilihat dari sudut pandang dompet Anda: CREDIT berarti dana masuk, dan DEBIT berarti dana keluar.

Kedua endpoint menuntut izin payouts:read, bukan payments:read. Saldo menyangkut dana yang tersimpan, sehingga kunci yang hanya membuat tagihan tidak perlu mengetahuinya.

Pencairan dana

Saldo yang terkumpul dari pembayaran lunas dapat ditarik ke rekening bank yang sudah terverifikasi. Nominal ditahan sejak permintaan dibuat, sehingga saldo tidak dapat dipakai dua kali.

Kode bank tujuan tidak boleh ditebak. Ambil daftarnya dari sini, lalu pakai nilai code apa adanya saat menambah rekening tujuan. Scope yang dibutuhkanpayouts:read.

curl https://api.langsunggas.example/api/v1/payout-banks \
  -H "Authorization: Bearer lg_live_a1b2c3d4_xxxxxxxxxxxxxxxx"

{
  "environment": "LIVE",
  "data": [
    {
      "code": "BCA",
      "name": "Bank Central Asia (BCA)",
      "can_validate_name": true
    },
    {
      "code": "BNI",
      "name": "Bank Negara Indonesia (BNI)",
      "can_validate_name": true
    }
  ],
  "count": 149,
  "request_id": "req_2f2f9a1c-2a6f-4f4a-9d18-0d6f6a52e9c1"
}

Kolom can_validate_name menyatakan bahwa bank tersebut mendukung pencocokan nama pemilik rekening di sisi penyedia. Pemeriksaan itu belum aktif pada akun kami, sehingga nama pemilik tetap dicocokkan operator sebelum rekening dapat menerima dana. Perlakukan kolom ini sebagai keterangan, bukan jaminan bahwa nama sudah diperiksa.

Rekening tujuan disertakan langsung pada permintaan. Tidak ada pendaftaran yang harus dilakukan lebih dahulu.

Kode bank tidak boleh ditebak. Ambil dari GET /api/v1/payout-banks, lalu pakai nilai code apa adanya. Kode yang tidak dikenal penyedia dijawab BANK_NOT_FOUND.

curl -X POST https://api.langsunggas.example/api/v1/payouts \
  -H "Authorization: Bearer $LG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "PO-2026-0001",
    "amount": 250000,
    "bank_code": "BNI",
    "account_number": "1234567890",
    "account_name": "PT Contoh Sejahtera",
    "metadata": { "catatan": "penarikan mingguan" }
  }'

{
  "id": "cmt2tsz6o000k3sywuw48ja4k",
  "reference_id": "PO-2026-0001",
  "amount": 250000,
  "status": "PENDING_APPROVAL",
  "mode": "MANUAL",
  "requires_approval": true,
  "created_at": "2026-08-21T10:48:11.040Z",
  "request_id": "req_1cdd48a7-b96f-431c-b8b5-5e12f100cea9"
}

Kunci API harus memiliki scope payouts:write untuk mengajukan dan payouts:read untuk membaca.

Mode pencairan ditetapkan oleh operator pada setiap merchant.

Nominal di atas batas otomatis tetap menunggu persetujuan, apa pun modenya.

{
  "id": "cmt2tsz6o000k3sywuw48ja4k",
  "reference_id": "PO-2026-0001",
  "amount": 250000,
  "status": "COMPLETED",
  "mode": "MANUAL",
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-08-21T10:48:11.040Z",
  "approved_at": "2026-08-21T11:02:44.180Z",
  "sent_at": "2026-08-21T11:02:46.902Z",
  "completed_at": "2026-08-21T11:04:10.551Z",
  "request_id": "req_d9019bf2-550f-4323-9e5d-8d3482ea00c6"
}

Daftar memakai penomoran berbasis kursor, sama seperti daftar pembayaran. Hanya pencairan pada lingkungan kunci yang dipakai yang ditampilkan.

{
  "data": [
    {
      "id": "cmt2tsz6o000k3sywuw48ja4k",
      "reference_id": "PO-2026-0001",
      "amount": 250000,
      "status": "PENDING_APPROVAL",
      "mode": "MANUAL",
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-08-21T10:48:11.040Z",
      "completed_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "cmt2tb5oe00333s84ei17uis1",
  "request_id": "req_ee24eaa8-512c-4499-94d3-4251001593e8"
}

{
  "error": {
    "code": "BELOW_MINIMUM",
    "message": "Nominal pencairan paling sedikit 50.000.",
    "request_id": "req_93462893-ed67-4223-ab02-b0d1c0f91330",
    "details": []
  }
}

Ketika pencairan mencapai keadaan akhir, kami mengirim notifikasi ke alamat yang sama dengan notifikasi pembayaran. Anda tidak perlu menanyakan status berulang kali.

{
  "id": "evt_6adb8f7a-f2e4-4d07-8129-5f1cf650744e",
  "type": "payout.completed",
  "created_at": "2026-08-21T12:27:32.976Z",
  "livemode": false,
  "data": {
    "payout_id": "cmt2xcq01000k3sm0uyk2nzoc",
    "reference_id": "PO-2026-0001",
    "amount": 200000,
    "status": "COMPLETED"
  }
}

{
  "id": "evt_66ac771b-5c82-4995-a199-8514ff2198f8",
  "type": "payout.failed",
  "created_at": "2026-08-21T12:27:35.309Z",
  "livemode": false,
  "data": {
    "payout_id": "cmt2xcse600193sm0l3y4kfz1",
    "reference_id": "PO-2026-0002",
    "amount": 150000,
    "status": "FAILED",
    "failure_code": "INVALID_DESTINATION",
    "failure_message": "Rekening tujuan ditolak bank."
  }
}

Pembayaran USDT

Selain rupiah, tagihan dapat diterbitkan dalam USDT untuk pelanggan luar negeri. Setiap tagihan memperoleh alamat setor tersendiri, sehingga pembayaran langsung teridentifikasi tanpa memo atau kode unik.

Metode yang tersedia: USDT_TRC20 pada jaringan TRON dan USDT_BEP20 pada jaringan BSC. Nominal ditulis pada amount dalam mikro-USDT, yaitu USDT dikali satu juta. Mata uang tagihan mengikuti metode yang dipilih, sehingga currency tidak perlu dikirim. Satuan bulat ini dipakai agar tidak ada pembulatan pecahan yang menyimpang.

{
  "reference_id": "order-usdt-001",
  "amount": 25000000,
  "method": { "type": "USDT_TRC20" },
  "customer": { "email": "buyer@example.com" }
}

Nilai 25000000 di atas berarti 25 USDT. Respons memuat alamat setor beserta keterangan jaringan:

{
  "id": "pay_...",
  "reference_id": "order-usdt-001",
  "status": "PENDING",
  "amount": 25000000,
  "currency": "USDT",
  "method": {
    "type": "USDT_TRC20",
    "channel": null,
    "chain": "TRON",
    "deposit_address": "T...",
    "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount_atomic": "25000000",
    "decimals": 6,
    "confirmations_required": 20
  },
  "expires_at": "2026-01-01T10:00:00.000Z"
}

Kode kanal untuk kedua metode sama dengan nama metodenya, yaituUSDT_TRC20 dan USDT_BEP20, dan keduanya berada pada kelompok CRYPTO saat daftar kanal dibaca.

Tagihan berpindah ke PAID setelah jumlah konfirmasi terpenuhi, lalu notifikasipayment.paid dikirim seperti pembayaran rupiah. Sebelum konfirmasi terpenuhi, dana yang sudah terlihat masuk belum diakui sebagai lunas.

Saldo USDT tercatat terpisah dari saldo rupiah dan ditarik lewat menu USDT pada dasbor. Alamat tujuan penarikan wajib didaftarkan lebih dahulu dan baru dapat dipakai setelah masa tunggu 24 jam berlalu, sehingga alamat asing yang disisipkan pihak lain masih sempat diketahui pemilik akun.

Penarikan USDT

Saldo USDT ditarik ke alamat milik merchant sendiri. Alurnya dua langkah: daftarkan alamat lebih dahulu, lalu ajukan penarikan ke alamat yang sudah aktif.

Mendaftarkan alamat tujuan:

curl -X POST https://api.langsunggas.shop/api/v1/crypto-withdrawals/addresses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "TRON",
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }'

{
  "id": "cwa_...",
  "chain": "TRON",
  "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "active_at": "2026-01-02T09:00:00.000Z",
  "cooldown_hours": 24
}

Membaca daftar alamat tujuan:

Medan usable bernilai benar hanya bila masa tunggu alamat sudah lewat. Alamat yang sudah dicabut tidak ikut terbawa. Izin yang dibutuhkan crypto-withdrawals:read.

{
  "data": [
    {
      "id": "cwa_...",
      "chain": "TRON",
      "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "ACTIVE",
      "usable": true,
      "active_at": "2026-01-02T09:00:00.000Z",
      "created_at": "2026-01-01T09:00:00.000Z"
    }
  ],
  "request_id": "req_xxxxxxxx"
}

Mengajukan penarikan:

curl -X POST https://api.langsunggas.shop/api/v1/crypto-withdrawals \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "wd-2026-0001",
    "chain": "TRON",
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "amount": "25.5"
  }'

{
  "id": "cw_...",
  "reference_id": "wd-2026-0001",
  "chain": "TRON",
  "amount": "25.500000",
  "amount_micro": "25500000",
  "status": "APPROVED",
  "requires_approval": false,
  "environment": "SANDBOX",
  "idempotent_replay": false,
  "created_at": "2026-01-02T10:00:00.000Z"
}

Status PENDING_APPROVAL berarti nominalnya melampaui ambang dan menunggu persetujuan operator. StatusAPPROVED berarti penarikan masuk antrean pengiriman ke jaringan.

Membaca satu penarikan beserta jejak lengkapnya:

Pengenal yang diterima berupa id maupunreference_id, sehingga penarikan tetap dapat ditelusuri walau jawaban permintaan pertama tidak pernah diterima.

{
  "id": "cw_...",
  "reference_id": "wd-2026-0001",
  "status": "CONFIRMED",
  "amount": "25.500000",
  "tx_hash": "0x...",
  "failure_code": null,
  "events": [
    {
      "from_status": null,
      "to_status": "APPROVED",
      "message": "Penarikan diajukan dan masuk antrean pengiriman.",
      "actor": "api",
      "created_at": "2026-01-02T10:00:00.000Z"
    },
    {
      "from_status": "APPROVED",
      "to_status": "BROADCASTING",
      "message": "Penarikan sedang disusun dan disiarkan ke jaringan TRON.",
      "actor": "system",
      "created_at": "2026-01-02T10:02:00.000Z"
    },
    {
      "from_status": "BROADCASTING",
      "to_status": "CONFIRMED",
      "message": "Transaksi berhasil disiarkan ke jaringan.",
      "actor": "system",
      "tx_hash": "0x...",
      "created_at": "2026-01-02T10:02:30.000Z"
    }
  ]
}

Daftar penarikan dibaca lewatGET /api/v1/crypto-withdrawals dengan penyaringstatus, limit, dancursor.

Notifikasi

Ketika status pembayaran berubah, kami mengirim pemberitahuan ke alamat yang Anda daftarkan pada halaman Notifikasi.

{
  "id": "evt_xxxxxxxxxxxx",
  "type": "payment.paid",
  "created_at": "2026-08-21T03:01:05Z",
  "livemode": true,
  "data": {
    "payment": {
      "id": "pay_xxxxxxxxxxxx",
      "reference_id": "PESANAN-2026-0001",
      "status": "PAID",
      "amount": 275000,
      "paid_at": "2026-08-21T03:01:04Z"
    }
  }
}

Kolom type menyatakan peristiwa yang terjadi. Abaikan jenis yang belum Anda kenali, karena daftar ini dapat bertambah.

Tiga jenis account.* menyangkut akun, bukan satu transaksi. Berkas kelayakan mengikat badan usaha dan penangguhan mematikan kedua lingkungan sekaligus, sehingga peristiwa ini dikirim ke setiap alamat notifikasi aktif yang Anda miliki, termasuk alamat uji. Karena itu livemode pada peristiwa akun menyatakan alamat mana yang menerimanya, bukan lingkungan tempat perubahan terjadi.

Isi data berbeda menurut jenisnya. Notifikasi pembayaran membawa payment_id, sedangkan notifikasi pencairan membawa payout_id,reference_id, amount, danstatus.

Pengiriman dianggap berhasil hanya bila sistem Anda menjawab dengan kode 2xx dalam sepuluh detik. Bila gagal, pengiriman diulang dengan jeda menaik: satu menit, lima menit, tiga puluh menit, dua jam, delapan jam, lalu dua puluh empat jam.

Mengatur notifikasi lewat API

Alamat notifikasi dapat disetel, diperiksa, dan rahasianya diputar tanpa membuka halaman web. Alamat dan rahasia terpisah per lingkungan, dan lingkungannya selalu diambil dari kunci yang Anda pakai memanggil.

Menyetel alamat. Dipakai juga untuk memperbaruinya di kemudian hari.

curl -X PUT https://api.langsunggas.shop/api/v1/webhook-endpoint \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://usaha-anda.com/notifikasi" }'

{
  "endpoint": {
    "id": "whe_xxxxxxxxxxxx",
    "url": "https://usaha-anda.com/notifikasi",
    "is_active": true,
    "environment": "SANDBOX"
  },
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx",
  "request_id": "req_xxxxxxxx"
}

Alamat yang mengarah ke jaringan internal, memakai protokol selain http dan https, atau memuat nama pengguna dan sandi akan ditolak. Pembatasan itu menjaga agar peladen kami tidak dapat disuruh mengetuk jaringan pribadi memakai alamat yang Anda tentukan.

Memeriksa keadaan alamat beserta ringkasan pengiriman, berguna untuk memantau apakah sistem Anda sanggup menerima notifikasi.

{
  "environment": "SANDBOX",
  "endpoint": {
    "id": "whe_xxxxxxxxxxxx",
    "url": "https://usaha-anda.com/notifikasi",
    "is_active": true,
    "created_at": "2026-10-10T10:12:32.003Z"
  },
  "secret_available": true,
  "deliveries": {
    "total": 128,
    "succeeded": 124,
    "failed": 3,
    "pending": 1,
    "dead_letter": 0
  }
}

Nilai dead_letter yang bertambah berarti ada notifikasi yang berhenti dicoba setelah semua percobaan ulang habis. Itu tanda alamat Anda sedang bermasalah dan perlu diperiksa.

Kolom action menerima rotate_secret, enable, atau disable.

curl -X POST https://api.langsunggas.shop/api/v1/webhook-endpoint \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "action": "rotate_secret" }'

Riwayat notifikasi

Melihat notifikasi mana yang gagal sampai, beserta sebabnya. Tanpa ini, pembayaran tampak hilang di sisi Anda padahal dana sudah masuk, dan satu-satunya bukti sebabnya hanya terbaca pada dasbor.

curl "https://api.langsunggas.shop/api/v1/webhook-deliveries?status=DEAD_LETTER&limit=10" \
  -H "Authorization: Bearer lg_sandbox_kunci_anda"

{
  "environment": "SANDBOX",
  "data": [
    {
      "id": "whd_xxxxxxxxxxxx",
      "event_id": "evt_xxxxxxxxxxxx",
      "event_type": "payment.paid",
      "attempt": 5,
      "status": "DEAD_LETTER",
      "response_code": 500,
      "error_message": "Peladen Anda menjawab 500.",
      "next_retry_at": null,
      "created_at": "2026-10-15T06:33:47.442Z"
    }
  ],
  "has_more": false,
  "dead_letter_count": 1
}

dead_letter_count adalah jumlah notifikasi yang sudah berhenti dicoba. Angka itulah yang menentukan perlu tidaknya pengiriman ulang, sehingga Anda tidak perlu menyaring seluruh riwayat untuk mengetahuinya.

curl -X POST https://api.langsunggas.shop/api/v1/webhook-deliveries \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "action": "redeliver", "all": true }'

{
  "action": "redeliver",
  "scheduled": 3,
  "environment": "SANDBOX"
}

Pengiriman ulang hanya menjadwalkan; kiriman sesungguhnya tetap dilakukan pekerja latar. scheduled bernilai nol berarti notifikasi itu sudah terjadwal sebelumnya, bukan gagal.

Simulasi pembayaran

Melunasi tagihan uji tanpa dana sungguhan, sehingga alur pembayaran Anda dapat diuji sampai tuntas tanpa membuka dasbor. Tanpa ini, tagihan dapat dibuat tetapi tidak ada cara membuatnya lunas.

curl -X POST https://api.langsunggas.shop/api/v1/simulate \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Content-Type: application/json" \
  -d '{ "reference_id": "pesanan-001", "apply_directly": true }'

{
  "payment_id": "pay_xxxxxxxxxxxx",
  "reference_id": "pesanan-001",
  "amount": 100000,
  "method": "LOCAL",
  "message": "Pembayaran disimulasikan dan tagihan telah dilunasi."
}

Kolom method pada jawaban bernilai LOCAL bila tagihan sudah lunas saat jawaban terbit, atau PROVIDER bila status baru berubah setelah notifikasi penyedia tiba. Pakai apply_directly ketika alamat notifikasi Anda belum dapat dijangkau dari luar, misalnya saat masih berjalan di mesin lokal.

Verifikasi tanda tangan

Contoh dengan Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

// Ambil isi mentah, jangan diuraikan lebih dulu.
const rawBody = await request.text();
const timestamp = request.headers.get("x-webhook-timestamp");
const signature = request.headers.get("x-webhook-signature");

// Tolak notifikasi lama untuk mencegah pengiriman ulang.
if (Math.abs(Date.now() - Number(timestamp)) / 1000 > 300) {
  return new Response(null, { status: 400 });
}

const diharapkan = createHmac("sha256", RAHASIA_ANDA)
  .update(timestamp + "." + rawBody)
  .digest("hex");

const a = Buffer.from(diharapkan);
const b = Buffer.from(signature);

if (a.length !== b.length || timingSafeEqual(a, b) === false) {
  return new Response(null, { status: 400 });
}

const event = JSON.parse(rawBody);
return new Response(null, { status: 200 });

Contoh dengan PHP:

<?php
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];

if (abs(round(microtime(true) * 1000) - (int)$timestamp) / 1000 > 300) {
    http_response_code(400);
    exit;
}

$diharapkan = hash_hmac('sha256', $timestamp . '.' . $rawBody, RAHASIA_ANDA);

if (!hash_equals($diharapkan, $signature)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);
http_response_code(200);

Status pembayaran

CREATED  ->  PENDING  ->  PAID
                 |
                 +-->  EXPIRED / FAILED / CANCELLED

Kode kesalahan

Seluruh kesalahan memakai bentuk yang sama.

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Nominal di luar batas yang diizinkan",
    "request_id": "req_xxxxxxxx",
    "details": []
  }
}

Batas permintaan

Melampaui batas menghasilkan kode 429. Tunggu sesuai tajukRetry-After sebelum mencoba lagi.

Praktik yang disarankan

• Simpan nilai id yang kami kembalikan, bukan hanya nomor pesanan Anda sendiri.
• Sediakan pemeriksaan berkala sebagai cadangan bila notifikasi tidak kunjung tiba, misalnya karena peladen Anda sempat mati.
• Catat setiap notifikasi yang masuk beserta hasil pemeriksaan tanda tangannya, agar penelusuran masalah lebih mudah.
• Uji seluruh alur pada lingkungan sandbox, termasuk keadaan gagal, sebelum beralih ke produksi.