Wawancara Backend: Bagaimana Anda Merancang API Pay-Per-Request HTTP 402/x402?

Pertanyaan

Anda perlu menambahkan akses bayar-per-permintaan (pay-per-request) ke sebuah API data. Permintaan yang belum dibayar harus mengembalikan HTTP 402, dan klien harus mengulang permintaan awal setelah membayar. Jelaskan status 402 dalam RFC 9110 dan rancang protokol end-to-end mirip x402 yang mencakup persyaratan pembayaran, verifikasi bukti, pengikatan sumber daya, perlindungan replay, idempotensi, pengembalian dana, dan rekonsiliasi.

Apa yang diuji oleh pewawancara

• Apakah Anda membedakan arti terstandardisasi 402 dari skema pembayaran konkret: RFC 9110 mencadangkan kode status tersebut tetapi tidak mendefinisikan jaringan pembayaran, mata uang, atau format respons.
• Apakah Anda mengikat bukti pembayaran ke sumber daya, jumlah, penerima, jaringan, dan masa kedaluwarsa sehingga pembayaran tidak dapat dipindahkan ke permintaan lain.
• Apakah Anda menangani percobaan ulang klien, batas waktu (timeout), tagihan ganda, keterlambatan konfirmasi blockchain, dan konsistensi akuntansi.
• Apakah Anda dapat menyatakan batas kepercayaan di antara layanan pembayaran, layanan sumber daya, pihak penyelesaian, dan log audit.

Jawaban model

402 terdaftar sebagai "Payment Required" dalam registri kode status HTTP. RFC 9110 mencadangkannya tetapi tidak mendefinisikan protokol pembayaran universal. Sebuah protokol harus memperlakukan 402 sebagai challenge yang dapat dibaca mesin, bukan sebagai bukti bahwa pembayaran telah terjadi.

Layanan sumber daya dapat mengembalikan persyaratan pembayaran yang unik dalam respons 402. Ini harus mencakup pengidentifikasi sumber daya, metode dan jalur, jumlah, aset, jaringan, penerima, masa kedaluwarsa, dan nonce. Klien menandatangani atau membayar tepat untuk field-field tersebut. Layanan atau fasilitator tepercaya memverifikasi bukti tersebut, memeriksa jumlah, penerima, jaringan, dan sumber daya, lalu memberikan tanda terima sekali pakai ke layanan sumber daya.

Layanan sumber daya harus mencatat hubungan idempoten antara id permintaan dan id pembayaran sebelum mengeksekusi operasi yang memakan banyak sumber daya. Percobaan ulang dengan id permintaan yang sama akan mengembalikan hasil yang sama atau status pemrosesan yang eksplisit. Pembayaran yang berhasil tidak berarti eksekusi sumber daya berhasil, sehingga pembayaran, otorisasi, eksekusi, dan pengembalian dana memerlukan status yang dapat dilacak. Pekerjaan rekonsiliasi harus menemukan perbedaan antara konfirmasi rantai (on-chain), catatan layanan, dan pengiriman aktual.

Sketsa implementasi

Pseudocode di bawah ini menunjukkan challenge inti dan batas-batas percobaan ulang; sistem produksi juga memerlukan pemverifikasi pembayaran, penyimpanan idempoten, dan pencatatan audit.

handle(request):
  id = request.idempotencyKey
  if receiptStore.has(id):
    return receiptStore.result(id)

  requirement = makeRequirement(
    resource = canonicalResource(request),
    amount = quote(request),
    network = "base",
    expiresAt = now + 60s,
    nonce = randomBytes(16)
  )

  proof = request.headers["Payment-Proof"]
  if proof is missing:
    return 402, { "payment-required": requirement }

  payment = verifyProof(proof, requirement)
  if payment.invalid or payment.expired or payment.replayed:
    return 402, { "payment-required": requirement, "reason": "invalid-proof" }

  result = executeOnce(id, request, payment)
  receiptStore.put(id, payment.id, result)
  return 200, result

Invarian kuncinya adalah bahwa canonicalResource dan verifyProof menggunakan aturan normalisasi yang sama. Jika tidak, satu sumber daya dapat memiliki beberapa representasi string dan verifikasi tanda tangan dapat tidak sesuai dengan otorisasi. executeOnce memerlukan batasan unik (unique constraint), transaksi, atau status tahan lama (durable state) sehingga percobaan ulang tidak dapat menduplikasi efek samping.

Jebakan umum

• Menganggap 402 menyertakan alur pembayaran. Ini hanya menyatakan bahwa pembayaran diperlukan; protokol harus mendefinisikan field dan aturan verifikasi.
• Hanya memeriksa jumlah sambil mengabaikan sumber daya, jaringan, penerima, aset, atau masa kedaluwarsa, yang memungkinkan substitusi lintas sumber daya atau replay lintas jaringan.
• Mengeksekusi efek samping segera setelah konfirmasi pembayaran tanpa catatan permintaan yang idempoten, sehingga percobaan ulang akibat batas waktu menagih atau membuat sumber daya dua kali.
• Memperlakukan transaksi rantai yang dikirimkan sebagai penyelesaian akhir; keterlambatan konfirmasi, reorg, kegagalan fasilitator, dan pengembalian dana adalah bagian dari state machine.
• Menempatkan bukti pembayaran dalam log atau URL, yang menciptakan kebocoran kredensial dan risiko replay.

Trade-off produksi

Untuk operasi baca bernilai rendah dan berisiko rendah, kuotasi berdurasi singkat, nonce sekali pakai, dan rekonsiliasi akhir asinkron mungkin dapat diterima. Operasi tulis bernilai tinggi harus mendapatkan status penyelesaian yang dapat diverifikasi sebelum pengiriman dan dieksekusi di balik transaksi idempoten. Jika klien tidak memiliki kemampuan dompet atau on-chain, fasilitator dapat membayar atas nama mereka, tetapi cakupan kepercayaan, biaya, batasan, dan fallback kegagalannya harus eksplisit.

Protokol ini juga memerlukan aturan untuk perubahan harga, challenge yang kedaluwarsa, pembayaran parsial, pembayaran berhasil yang diikuti oleh kegagalan sumber daya, pengembalian dana, dan penurunan performa layanan. Cache tidak boleh membagikan respons yang berisi bukti pembayaran dengan prinsipal lain; kuncinya harus menyertakan hasil otorisasi, atau cache hanya boleh menyimpan challenge 402 publik.

Referensi

• RFC 9110 HTTP Semantics: semantik registrasi 402 dan batasan status HTTP.
• x402 Introduction: konsep protokol pay-per-request berbasis challenge dan tanpa akun.
• Coinbase HTTP 402 Core Concepts: batas implementasi untuk persyaratan pembayaran, verifikasi, dan akses sumber daya.

Pertanyaan lanjutan

Bagaimana cara Anda mencegah satu bukti pembayaran digunakan untuk dua sumber daya?

Masukkan metode, jalur, ringkasan kueri (query digest), atau ID sumber daya yang telah dinormalisasi ke dalam persyaratan pembayaran dan cakup field-field tersebut dengan bukti tersebut. Layanan menghitung ulang ringkasan dengan algoritma normalisasi yang sama dan mencatat setiap nonce atau ID pembayaran sebagai penggunaan tunggal.

Haruskah challenge 402 berada di header atau di badan respons?

Tentukan format versi yang dapat dibaca mesin terlebih dahulu. Header cocok untuk petunjuk kecil, sedangkan badan respons dapat memuat persyaratan pembayaran multi-field. Apa pun pilihannya, batasi ukurannya, deklarasikan tipe kontennya, dan hindari menempatkan kredensial sensitif di header yang dapat di-cache.

Bagaimana jika pembayaran berhasil tetapi eksekusi bisnis gagal?

Pertahankan pembayaran, otorisasi, eksekusi, dan pengembalian dana sebagai status terpisah yang dihubungkan oleh ID permintaan. Jika operasi tidak dapat diulang, masukkan ke antrean pengembalian dana atau rekonsiliasi manual. Jika dapat diulang, kembalikan status pemrosesan dan buat pembacaan selanjutnya mengembalikan hasil yang sama.

Apakah x402 memerlukan blockchain?

Materi x402 saat ini menggunakan pembayaran on-chain atau fasilitator sebagai contoh, tetapi HTTP 402 itu sendiri tidak menentukan jaringan penyelesaian. Pisahkan semantik kode status dari jalur pembayaran (payment rail); mengubah jalur memerlukan pendefinisian ulang bukti, finalitas, dan semantik pengembalian dana.

Bagaimana Anda memverifikasi bahwa sistem tidak pernah menagih dua kali?

Tambahkan batasan unik untuk ID pembayaran, ID permintaan, dan operasi bisnis; catat setiap hasil verifikasi dan eksekusi; dan suntikkan kegagalan yang mencakup batas waktu klien, restart layanan, panggilan balik pemverifikasi duplikat, dan rekonsiliasi yang tertunda.