Temu Duga Backend: Bagaimanakah Anda Akan Mereka Bentuk API Bayar-Setiap-Permintaan HTTP 402/x402?

Soalan

Anda perlu menambah akses bayar-setiap-permintaan (pay-per-request) pada API data. Permintaan yang belum dibayar harus mengembalikan HTTP 402, dan klien harus mencuba semula permintaan asal selepas membayar. Terangkan status 402 dalam RFC 9110 dan reka bentuk protokol hujung-ke-hujung seperti x402 yang merangkumi keperluan pembayaran, pengesahan bukti, pengikatan sumber, perlindungan main semula, keidempotenan, bayaran balik dan penyelarasan.

Perkara yang diuji oleh penemu duga

• Sama ada anda membezakan makna piawai 402 daripada skema pembayaran yang konkrit: RFC 9110 menyimpan kod status tersebut tetapi tidak mentakrifkan rangkaian pembayaran, mata wang atau format respons.
• Sama ada anda mengikat bukti pembayaran kepada sumber, amaun, penerima, rangkaian dan tamat tempoh supaya pembayaran tidak boleh dipindahkan ke permintaan lain.
• Sama ada anda mengendalikan percubaan semula klien, tamat masa, caj pendua, kelewatan pengesahan blok rantai dan ketekalan perakaunan.
• Sama ada anda boleh menyatakan sempadan kepercayaan antara perkhidmatan pembayaran, perkhidmatan sumber, pihak penyelesaian dan log audit.

Jawapan model

402 didaftarkan sebagai "Payment Required" dalam pendaftaran kod status HTTP. RFC 9110 menyimpannya tetapi tidak mentakrifkan protokol pembayaran universal. Sesuatu protokol harus menganggap 402 sebagai cabaran yang boleh dibaca mesin, bukan sebagai bukti bahawa pembayaran telah pun berlaku.

Perkhidmatan sumber boleh mengembalikan keperluan pembayaran yang unik dalam respons 402. Ia harus merangkumi pengecam sumber, kaedah dan laluan, amaun, aset, rangkaian, penerima, tamat tempoh dan nonce. Klien menandatangani atau membayar tepat untuk medan-medan tersebut. Perkhidmatan atau pemudah cara yang dipercayai mengesahkan bukti tersebut, menyemak amaun, penerima, rangkaian dan sumber, kemudian memberikan resit sekali guna kepada perkhidmatan sumber.

Perkhidmatan sumber harus merekodkan hubungan idempoten antara id permintaan dan id pembayaran sebelum melaksanakan operasi yang menggunakan banyak sumber. Percubaan semula dengan id permintaan yang sama mengembalikan hasil yang sama atau status pemprosesan yang jelas. Pembayaran yang berjaya tidak membayangkan pelaksanaan sumber yang berjaya, jadi pembayaran, pengesahan, pelaksanaan dan bayaran balik memerlukan status yang boleh dikesan. Kerja penyelarasan harus mencari perbezaan antara pengesahan rantaian, rekod perkhidmatan dan penghantaran sebenar.

Lakaran pelaksanaan

Pseudokod di bawah menunjukkan cabaran teras dan sempadan percubaan semula; sistem pengeluaran juga memerlukan pengesah pembayaran, storan idempoten dan pengelogan 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 utama ialah canonicalResource dan verifyProof menggunakan peraturan normalisasi yang sama. Jika tidak, satu sumber boleh mempunyai berbilang perwakilan rentetan dan pengesahan tandatangan boleh tidak bersetuju dengan kebenaran. executeOnce memerlukan kekangan unik, transaksi atau keadaan tahan lama supaya percubaan semula tidak boleh menduplikasi kesan sampingan.

Perangkap biasa

• Menganggap 402 merangkumi aliran pembayaran. Ia hanya menyatakan bahawa pembayaran diperlukan; protokol mesti mentakrifkan medan dan peraturan pengesahan.
• Hanya menyemak amaun sambil mengabaikan sumber, rangkaian, penerima, aset atau tamat tempoh, yang membolehkan penggantian rentas sumber atau main semula rentas rangkaian.
• Melaksanakan kesan sampingan serta-merta selepas pengesahan pembayaran tanpa rekod permintaan idempoten, menyebabkan percubaan semula akibat tamat masa mengenakan caj atau mencipta sumber sebanyak dua kali.
• Menganggap transaksi rantaian yang dihantar sebagai penyelesaian muktamad; kelewatan pengesahan, penyusunan semula (reorg), kegagalan pemudah cara dan bayaran balik tergolong dalam mesin keadaan.
• Meletakkan bukti pembayaran dalam log atau URL, mewujudkan kebocoran kelayakan dan risiko main semula.

Pertukaran kompromi pengeluaran

Bagi operasi bacaan bernilai rendah dan berisiko rendah, sebut harga jangka pendek, nonce sekali guna dan penyelarasan akhir tak segerak mungkin boleh diterima. Operasi penulisan bernilai tinggi harus mendapatkan status penyelesaian yang boleh disahkan sebelum penghantaran dan dilaksanakan di sebalik transaksi idempoten. Jika klien tidak mempunyai dompet atau keupayaan dalam rantaian, pemudah cara boleh membayar bagi pihak mereka, tetapi skop kepercayaan, yuran, had dan sandaran kegagalannya mestilah jelas.

Protokol ini juga memerlukan peraturan untuk perubahan harga, cabaran yang telah tamat tempoh, pembayaran separa, pembayaran berjaya diikuti oleh kegagalan sumber, bayaran balik dan kemerosotan perkhidmatan. Cache tidak boleh berkongsi respons yang mengandungi bukti pembayaran dengan prinsipal lain; kuncinya mesti menyertakan hasil kebenaran, atau ia hanya perlu menyimpan cabaran 402 awam dalam cache.

Rujukan

• RFC 9110 HTTP Semantics: semantik pendaftaran 402 dan kekangan status HTTP.
• x402 Introduction: konsep protokol bayar-setiap-permintaan berasaskan cabaran dan tanpa akaun.
• Coinbase HTTP 402 Core Concepts: sempadan pelaksanaan untuk keperluan pembayaran, pengesahan dan akses sumber.

Soalan susulan

Bagaimanakah anda menghalang satu bukti pembayaran daripada digunakan untuk dua sumber?

Letakkan kaedah, laluan, ringkasan pertanyaan (query digest) atau ID sumber yang dinormalkan ke dalam keperluan pembayaran dan lindungi medan tersebut dengan bukti tersebut. Perkhidmatan mengira semula ringkasan dengan algoritma normalisasi yang sama dan merekodkan setiap nonce atau ID pembayaran sebagai guna sekali.

Patutkah cabaran 402 berada dalam pengepala atau badan respons?

Takrifkan format yang boleh dibaca mesin dan mempunyai versi terlebih dahulu. Pengepala sesuai untuk pembayang kecil, manakala badan respons boleh membawa keperluan pembayaran berbilang medan. Walau apa pun, hadkan saiznya, nyatakan jenis kandungannya dan elakkan meletakkan kelayakan sensitif dalam pengepala yang boleh dicache.

Bagaimana jika pembayaran berjaya tetapi pelaksanaan perniagaan gagal?

Kekalkan pembayaran, kebenaran, pelaksanaan dan bayaran balik sebagai keadaan berasingan yang dipautkan oleh ID permintaan. Jika operasi tidak boleh dicuba semula, masukkan ke dalam baris gilir bayaran balik atau penyelarasan manual. Jika ia boleh dicuba semula, kembalikan status pemprosesan dan jadikan bacaan kemudian mengembalikan hasil yang sama.

Adakah x402 memerlukan blok rantai?

Bahan x402 semasa menggunakan pembayaran dalam rantaian atau pemudah cara sebagai contoh, tetapi HTTP 402 itu sendiri tidak menetapkan rangkaian penyelesaian. Asingkan semantik kod status daripada landasan pembayaran; menukar landasan memerlukan pentakrifan semula bukti, kemuktamadan dan semantik bayaran balik.

Bagaimanakah anda mengesahkan bahawa sistem tidak pernah mengenakan caj berganda?

Tambah kekangan unik untuk ID pembayaran, ID permintaan dan operasi perniagaan; rekod setiap hasil pengesahan dan pelaksanaan; dan suntik kegagalan yang merangkumi tamat masa klien, mula semula perkhidmatan, panggilan balik pengesah pendua dan penyelarasan yang tertunda.