Bayar permintaan pembayaran x402 Membayar tantangan MPP Integrasi kerangka kerja

Memproses pembayaran

Untuk memproses pembayaran, Anda memerlukan dua sumber daya:

Instrumen pembayaran — Dompet kripto tertanam dengan Coinbase atau Stripe. Lihat Membuat instrumen pembayaran.
Sesi pembayaran — Sesi terbatas waktu yang secara opsional memberlakukan anggaran pengeluaran. Lihat Membuat sesi pembayaran.

Setelah keduanya ada, hubungi ProcessPayment dengan ID sesi pembayaran, ID instrumen pembayaran, dan payload pembayaran. Layanan memvalidasi permintaan, memeriksa anggaran, menandatangani transaksi pada blockchain yang sesuai, dan mengembalikan hasil pembayaran yang ditandatangani. Untuk skema permintaan dan respons lengkap, lihat ProcessPayment di Referensi API.

AgentCore pembayaran mendukung dua protokol pembayaran, yang Anda pilih dengan paymentType parameter:

CRYPTO_X402— Protokol x402. Berikan payload pembayaran x402 merchantpaymentInput.cryptoX402, dan agen akan mencoba kembali permintaan dengan bukti yang ditandatangani di header. X-PAYMENT
MPP— Protokol Pembayaran Mesin (MPP). Teruskan WWW-Authenticate: Payment tantangan pedagang masukpaymentInput.mpp, dan agen akan mencoba kembali permintaan dengan kredensi yang dikembalikan di Authorization header.

Pilih paymentType yang cocok dengan protokol yang digunakan pedagang dalam 402 Payment Required responsnya. Untuk detail permintaan dan tanggapan x402, lihat Memb ayar permintaan pembayaran x402. Untuk detail permintaan dan tanggapan MPP, lihat Memb ayar tantangan MPP.

Tip

Anda dapat mengotomatiskan langkah-langkah di halaman ini dengan keterampilan AgentCore Pembayaran di toolkit AWS agen. Keterampilan ini adalah bagian dari plugin aws-agents dan memungkinkan agen pengkodean AI membuat Manajer Pembayaran, konektor, penyedia kredensia, instrumen pembayaran, dan sesi menggunakan agentcore CLI, dan menambahkan alat pembayaran proses ke agen Anda. Untuk detailnya, lihat Quickstart dan toolkit AWS agen aktif. GitHub

Ada lima cara untuk memanggil ProcessPayment API:

contoh

AgentCore CLI

Jika agen Anda digunakan dengan kemampuan pembayaran yang dikonfigurasi, panggil dengan konteks pembayaran dan pencegat x402 menangani pemrosesan pembayaran secara otomatis:


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

Untuk menggunakan sesi eksplisit alih-alih membuat sesi secara otomatis:


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --payment-session-id <SESSION_ID> \
  --payment-user-id user@example.com

Plugin x402 agen yang digunakan mencegat tanggapan HTTP 402, memanggilProcessPayment, dan mencoba ulang permintaan dengan bukti. Membutuhkan AgentCore CLI v0.19.0 atau yang lebih baru.

AgentCore SDK

Gunakan PaymentManager kelas untuk menghasilkan header pembayaran secara manual dalam kerangka agen apa pun:


import uuid
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=mgr["paymentManagerArn"],
    region_name="us-west-2"
)

# When you receive a 402 response, generate payment proof
payment_required_request = {
    "statusCode": 402,
    "headers": payment_required["headers"],
    "body": payment_required["body"],
}
payment_proof_headers = manager.generate_payment_header(
    user_id="test-user-123",
    payment_instrument_id=instrument["paymentInstrumentId"],
    payment_session_id=session["paymentSessionId"],
    payment_required_request=payment_required_request,
    client_token=str(uuid.uuid4()),
)

payment_proof_headersberisi header bukti pembayaran. Sertakan header ini saat mencoba kembali permintaan ke titik akhir berbayar. Anda juga dapat memanggil process_payment metode PaymentManager untuk kontrol lebih besar atas input.

AWS CLI

Contoh berikut memproses pembayaran x402 dengan meneruskan payload merchant: paymentInput.cryptoX402


aws bedrock-agentcore process-payment \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-session-id "payment-session-abc123" \
    --payment-instrument-id "payment-instrument-xyz789" \
    --payment-type "CRYPTO_X402" \
    --payment-input '{
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"}
            }
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

Untuk mempelajari cara membuat protokol paymentInput untuk setiap protokol, termasuk contoh MPP AWS CLI, lihat Memb ayar permintaan pembayaran x402 dan Memb ayar tantangan MPP.

AWS SDK

Contoh berikut memproses pembayaran x402 dengan menelepon process_payment dengan payload merchant di: paymentInput.cryptoX402


import uuid

payment = dp_client.process_payment(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    paymentType="CRYPTO_X402",
    paymentInput={
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"},
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Respons:


{
    "processPaymentId": "12345678-1234-1234-1234-123456789012",
    "paymentManagerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager-a1b2c3d4e5",
    "paymentSessionId": "payment-session-abc123def4567",
    "paymentInstrumentId": "payment-instrument-xyz789abc1234",
    "paymentType": "CRYPTO_X402",
    "status": "PROOF_GENERATED",
    "paymentOutput": {
        "cryptoX402": {
            "version": "2",
            "payload": {
                "...signed transaction proof..."
            }
        }
    },
    "createdAt": "2025-07-15T10:35:00Z",
    "updatedAt": "2025-07-15T10:35:02Z"
}

A status of PROOF_GENERATED menunjukkan transaksi telah ditandatangani dan bukti pembayaran disertakan di dalamnyapaymentOutput.

Untuk mempelajari cara membuat protokol paymentInput untuk setiap protokol, termasuk contoh MPP AWS SDK dan responsnya, lihat Memb ayar permintaan pembayaran x402 dan Memb ayar tantangan MPP.

Strands SDK

Plugin AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk Strands Agents. Ini mendukung protokol X402 Payment Required, memungkinkan agen untuk secara otomatis menangani tanggapan HTTP 402.

Instalasi:


pip install 'bedrock-agentcore[strands-agents]'

Konfigurasikan dan gunakan plugin:


from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin

# Configure the plugin
config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    payment_session_id="payment-session-xuzrnUCd7RT725G",
    region="us-west-2",
)

# Create the plugin
plugin = AgentCorePaymentsPlugin(config=config)

# Create agent with the plugin
agent = Agent(
    system_prompt="You are a helpful assistant that can access paid APIs.",
    tools=[http_request],
    plugins=[plugin],
)

# Use the agent -- 402 responses are automatically handled
agent("access https://drvd12nxpcyd5.cloudfront.net/market-recap")

Plugin AgentCore pembayaran mencegat permintaan pembayaran x402 secara otomatis, memproses pembayaran, dan mencoba kembali permintaan dengan bukti pembayaran untuk agen.

LangGraph

Middleware AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk LangGraph agen. Ini mendukung protokol X402 Payment Required, memungkinkan agen untuk secara otomatis menangani tanggapan HTTP 402.

Instalasi:


pip install 'bedrock-agentcore[langgraph]'

Konfigurasikan dan gunakan middleware:


from langchain.agents import create_agent
from bedrock_agentcore.payments.integrations.langgraph import (
    AgentCorePaymentsConfig,
    AgentCorePaymentsMiddleware,
)

config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
)

payments = AgentCorePaymentsMiddleware(config)

agent = create_agent(
    model="us.anthropic.claude-sonnet-4-20250514-v1:0",
    tools=[],
    middleware=[payments],
)

result = agent.invoke({"messages": [{"role": "user", "content": "access https://drvd12nxpcyd5.cloudfront.net/market-recap"}]})
print(result)

Middleware AgentCore pembayaran mencegat permintaan pembayaran x402 secara otomatis, memproses pembayaran, dan mencoba kembali permintaan dengan bukti pembayaran untuk agen.

Bayar permintaan pembayaran x402

Ketika pedagang merespons dengan payload pembayaran x402 dalam 402 Payment Required tanggapannya, Anda meneruskan payload tersebut ke AgentCore pembayaran, dan AgentCore pembayaran mengembalikan bukti yang ditandatangani. Anda menyalin payload merchant kepaymentInput.cryptoX402, dan AgentCore pembayaran memeriksa anggaran, menandatangani transaksi dengan dompet, dan mengembalikan bukti yang ditandatangani. Anda melampirkan bukti ke X-PAYMENT header dan mencoba lagi permintaan asli.

Permintaan dan tanggapan

Berikan bidang berikut dipaymentInput.cryptoX402:

version— Versi protokol x402 (misalnya, 1 atau2). Wajib.
payload— Persyaratan pembayaran x402 pedagang, diteruskan sebagai objek JSON. Ini menentukan bidang schemenetwork,maxAmountRequired,asset,payTo,, dan lainnya dari 402 respons pedagang. Wajib.
permit2AllowanceLimit— Tunjangan maksimum on-chain Permit2 untuk diberikan, dalam denominasi terkecil aset. Tidak wajib. Tetapkan ini hanya untuk skema upto (terukur), yang diselesaikan melalui kontrak Permit2; memasoknya untuk exact skema adalah kesalahan validasi. Lihat tunjangan Permit2 untuk pembayaran hingga.

Respons mengembalikan bidang berikut dipaymentOutput.cryptoX402:

version— Versi protokol x402.
payload— Bukti transaksi yang ditandatangani, sebagai objek JSON. Lampirkan ke X-PAYMENT header dan coba lagi permintaan asli.

A status of PROOF_GENERATED menunjukkan bahwa transaksi telah ditandatangani dan bukti pembayaran disertakan di dalamnyapaymentOutput.

Skema

Nama muatan x402 a. scheme AgentCore pembayaran mendukung skema berikut:

exact— Membayar jumlah tetap yang ditentukan dalam muatan pedagang. Ini adalah skema default, dan tidak memerlukan penanganan tunjangan.
upto— Membayar jumlah yang diukur hingga batas tertentu. Skema ini diselesaikan melalui kontrak Permit2, sehingga dompet pembayar harus memberikan tunjangan Permit2. Lihat tunjangan Permit2 untuk pembayaran hingga.

Tunjangan Permit2 untuk pembayaran hingga

S upto kema diselesaikan melalui kontrak Permit2, yang memindahkan dana dengan. transferFrom Dompet pembayar harus terlebih dahulu memberikan tun ERC-20 jangan Permit2, atau penyelesaian gagal dengan kesalahan pras Permit2-allowance yarat. Hibah ini mengikuti model persetujuan on-chain yang sama dengan persetujuan Permit2 langsung. Untuk informasi lebih lanjut, lihat Uniswap Permit2 di situs web Uniswap dan spesifikasi skema x402 up di situs web. GitHub

Untuk menangani ini, atur permit2AllowanceLimit ke tunjangan maksimum dalam denominasi terkecil aset (misalnya, 1000000 = 1 USDC pada 6 desimal). Untuk memberikan tunjangan tak terbatas, berikan uint256 nilai maksimum sebagai string:115792089237316195423570985008687907853269984665640564039457584007913129639935. Saat Anda menyetel bidang ini, AgentCore pembayaran mengirimkan approve transaksi on-chain sebelum menandatangani. Transaksi ini menimbulkan biaya jaringan blockchain (gas) yang dibayarkan dari saldo token asli dompet.

Karena approve menetapkan, alih-alih menambah, tunjangan dompet, ditetapkan permit2AllowanceLimit hanya ketika dompet perlu disetujui (misalnya, upto pembayaran pertamanya) untuk menghindari transaksi on-chain yang berlebihan. Hilangkan bidang untuk melewatkan penanganan tunjangan sepenuhnya. Bidang ini hanya berlaku untuk upto skema; memasokkannya untuk exact skema adalah kesalahan validasi.

Contoh berikut memproses upto pembayaran dan memberikan tunjangan 1 USDC ke Permit2. Karenaupto, maxAmountRequired membawa plafon yang diiklankan pedagang dalam 402 tanggapannya, dan extra.facilitatorAddress merupakan fasilitator penyelesaian dari respons yang sama.

contoh

Batasan

Bid permit2AllowanceLimit ang ini hanya valid untuk upto skema. Menyediakannya untuk exact skema mengembalikan aValidationException.

Untuk kesalahan validasi permintaan pembayaran x402 dan penyelesaiannya, lihat kesalahan permintaan pembayaran x402. Untuk kesalahan pemrosesan pembayaran dan penyelesaiannya, lihat Kesalahan pemrosesan pembayaran.

Membayar tantangan MPP

Ketika seorang pedagang mengembalikan WWW-Authenticate: Payment tantangan dalam 402 Payment Required tanggapannya, teruskan tantangan kata demi kata. paymentInput.mpp AgentCore pembayaran mengurai tantangan, memeriksa anggaran, menandatangani dengan dompet, dan mengembalikan nilai header siap dikirimAuthorization. AgentCore pembayaran menangani penguraian header, decoding base64url, dan penandatanganan, sehingga Anda tidak perlu melakukan operasi ini.

Permintaan dan tanggapan

Berikan bidang berikut dipaymentInput.mpp:

version— Versi protokol MPP (misalnya,1). Wajib.
wwwAuthenticateHeaders— Nilai WWW-Authenticate: Payment header mentah dari 402 respons pedagang, diteruskan kata demi kata. Berikan tepat satu header. Wajib.
buyerPaysGasFees— Apakah akan mengizinkan pembayaran biaya jaringan blockchain (gas) dari dompet pembeli ketika penjual tidak mensponsori mereka. Tidak wajib. Dihilangkan atau false berarti pembeli menolak. Lihat Per setujuan biaya jaringan.

Respons mengembalikan bidang berikut dipaymentOutput.mpp:

version— Versi protokol MPP.
selectedPaymentId— Tant id angan yang dibayar AgentCore pembayaran, bergema dari tantangan input sehingga Anda dapat mengkorelasikan hasilnya tanpa mendekode kredensialnya.
paymentCredential— Nilai Authorization header siap dikirim, dalam formulir. Payment <base64url-token> Lampirkan sebagai Authorization header dan coba lagi permintaan asli.

penting

Jangan memecahkan kode atau memodifikasipaymentCredential. Ini menyematkan tantangan asli dan muatan yang ditandatangani, dan HMAC pedagang mengikat ke byte yang tepat. Lampirkan nilai seperti yang dikembalikan.

Contoh berikut memproses tantangan MPP. Atur --payment-type "MPP" dan teruskan WWW-Authenticate: Payment tantangan pedagang kata demi kata dalam paymentInput.mpp.wwwAuthenticateHeaders (tepat satu header).

contoh

AWS CLI


aws bedrock-agentcore process-payment \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-session-id "payment-session-abc123" \
    --payment-instrument-id "payment-instrument-xyz789" \
    --payment-type "MPP" \
    --payment-input '{
        "mpp": {
            "version": "1",
            "wwwAuthenticateHeaders": [
                "Payment id=\"c1\", realm=\"seller.example.com\", method=\"evm\", intent=\"charge\", request=\"eyJhbW91bnQiOiIxMDAwMDAifQ\""
            ]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

AWS SDK


import uuid

payment = dp_client.process_payment(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    paymentType="MPP",
    paymentInput={
        "mpp": {
            "version": "1",
            "wwwAuthenticateHeaders": [
                'Payment id="c1", realm="seller.example.com", method="evm", '
                'intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAifQ"'
            ],
        }
    },
    clientToken=str(uuid.uuid4()),
)

Respons:


{
    "processPaymentId": "12345678-1234-1234-1234-123456789012",
    "paymentManagerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager-a1b2c3d4e5",
    "paymentSessionId": "payment-session-abc123def4567",
    "paymentInstrumentId": "payment-instrument-xyz789abc1234",
    "paymentType": "MPP",
    "status": "PROOF_GENERATED",
    "paymentOutput": {
        "mpp": {
            "version": "1",
            "selectedPaymentId": "c1",
            "paymentCredential": "Payment <base64url-token>"
        }
    },
    "createdAt": "2025-07-15T10:35:00Z",
    "updatedAt": "2025-07-15T10:35:02Z"
}

A status of PROOF_GENERATED menunjukkan kredenSIAL telah ditandatangani dan disertakan dipaymentOutput.mpp.paymentCredential.

Metode dan token

Tantangan MPP menyebutkan pembayaranmethod. AgentCore pembayaran mendukung metode berikut untuk charge maksud:

evm— Hanya USDC kanonik. Tantangannya harus mencakup methodDetails.chainId danrealm.
tempo— Setiap rantai Tempo, dipilih olehmethodDetails.chainId, menggunakan USDC-equivalent token yang dikenali jaringan.
solana— devnet Jaringan mainnet dan, dengan biaya yang disponsori server saja.

Jaringan blockchain instrumen pembayaran harus sesuai dengan metode tantangan. Dukungan penyedia tergantung pada jenis konektor:

Metode	CDP Coinbase	Garis (Privy)
`evm`	Didukung	Didukung
`tempo`	Didukung	Didukung
`solana`	Tidak didukung	Didukung

Persetujuan biaya jaringan

Biaya jaringan blockchain (gas) terpisah dari jumlah tantangan. Sebuah tantangan mengiklankan siapa yang mensponsori mereka melalui methodDetails.feePayer benderanya:

methodDetails.feePayer=true— Penjual mensponsori biaya jaringan. buyerPaysGasFeestidak berpengaruh.
methodDetails.feePayer=falseatau absen — Pembeli membayar biaya jaringan dari dompet pembayaran, selain jumlah pembayaran. Karena biaya itu tidak terlihat dalam jumlah tantangan, tanda AgentCore pembayaran hanya jika Anda menetapkanbuyerPaysGasFees=true; jika tidak maka akan mengembalikan aValidationException. Untuk tempo metode ini, persetujuan ini diperlukan setiap kali penjual tidak mensponsori biaya.

evmMetode ini tidak memerlukan persetujuan biaya, karena fasilitator menyiarkan transaksi dan membayar gas. solanaMetode ini hanya mendukung biaya yang disponsori server hari ini.

Batasan

AgentCore pembayaran memenuhi tepat satu tantangan per ProcessPayment panggilan. Berikan satu header diwwwAuthenticateHeaders.
Hanya mode charge maksud dan tarik yang didukung.
Tantangan MPP berumur pendek. Jika tantangan telah kedaluwarsa, AgentCore pembayaran mengembalikan a ValidationException dan tidak menghabiskan anggaran. Minta sumber daya berbayar lagi untuk mendapatkan tantangan baru, lalu coba lagi.

Untuk kesalahan validasi tantangan MPP dan resolusinya, lihat kesalahan tantangan MPP.

Integrasi kerangka kerja

Untuk dokumentasi referensi lengkap termasuk penanganan kesalahan, opsi konfigurasi, dan alat bawaan, lihat Integrasi kerangka kerja.

Kerangka Kerja	Jenis integrasi	Referensi
Agen Helai	Plugin (berbasis kait)	Penanganan interupsi, opsi konfigurasi, alat bawaan
LangGraph	Middleware (membungkus panggilan alat)	Panggilan balik kesalahan, daftar izin, dukungan asinkron, opsi konfigurasi

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Menghubungkan ke Bazaar

Integrasi kerangka kerja