處理付款

若要處理付款，您需要兩個資源：

付款工具 — 具有 Coinbase 或 Stripe 的內嵌加密錢包。請參閱建立付款工具。
付款工作階段 — 有時間限制的工作階段，可選擇性地強制執行支出預算。請參閱建立付款工作階段。

兩者都存在之後，ProcessPayment請使用付款工作階段 ID、付款工具 ID 和付款承載來呼叫。服務會驗證請求、檢查預算、在適當的區塊鏈上簽署交易，以及傳回已簽署的付款結果。如需完整的請求和回應結構描述，請參閱 API 參考中的 ProcessPayment。

AgentCore 付款支援兩種付款通訊協定，您可以使用 paymentType 參數選取：

CRYPTO_X402 — x402 通訊協定。在中提供商家的 x402 付款承載paymentInput.cryptoX402，代理程式會在 X-PAYMENT標頭中使用已簽署的證明重試請求。
MPP — 機器付款通訊協定 (MPP)。在中轉送商家WWW-Authenticate: Payment的挑戰paymentInput.mpp，代理程式會使用 Authorization標頭中傳回的登入資料重試請求。

選擇符合商家在402 Payment Required回應中使用的通訊協定paymentType的。如需 x402 請求和回應詳細資訊，請參閱支付 x402 付款請求。如需 MPP 請求和回應詳細資訊，請參閱支付 MPP 挑戰。

提示

您可以使用 AWS 客服人員工具組中的 AgentCore Payments 技能來自動化此頁面上的步驟。技能是 aws-agents 外掛程式的一部分，可讓 AI 編碼代理程式使用 CLI agentcore 建立您的 Payment Manager、連接器、登入資料提供者、付款工具及工作階段，並將程序付款工具新增至您的代理程式。如需詳細資訊，請參閱 GitHub 上的快速入門和客服人員工具組。 AWS GitHub

有五種方式可以叫用 ProcessPayment API：

範例

AgentCore CLI

如果您的代理程式已部署並設定付款功能，請使用付款內容叫用它，且 x402 攔截器會自動處理付款處理：


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

若要使用明確工作階段而非自動建立工作階段：


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

部署的代理程式 x402 外掛程式會攔截 HTTP 402 回應、呼叫 ProcessPayment，並使用證明重試請求。需要 AgentCore CLI 0.19.0 版或更新版本。

AgentCore SDK

使用 PaymentManager類別在任何代理程式架構內手動產生付款標頭：


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_headers 包含付款證明標頭。將請求重試至付費端點時，請包含此標頭。您也可以呼叫的 process_payment方法PaymentManager，以進一步控制輸入。

AWS CLI

下列範例透過在中傳遞商家的承載來處理 x402 付款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

若要了解如何paymentInput為每個通訊協定建置，包括 MPP AWS CLI 範例，請參閱支付 x402 付款請求和支付 MPP 挑戰。

AWS SDK

下列範例會透過在中使用商家的承載呼叫 process_payment 來處理 x402 付款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()),
)

回應：


{
    "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"
}

status 的 PROOF_GENERATED表示交易已簽署，且付款證明包含在中paymentOutput。

若要了解如何paymentInput為每個通訊協定建置，包括 MPP AWS SDK 範例及其回應，請參閱支付 x402 付款請求和支付 MPP 挑戰。

Strands SDK

AgentCore 付款外掛程式為 Strands Agents 提供自動付款處理。它支援 x402 Payment Required 通訊協定，可讓客服人員自動處理 HTTP 402 回應。

安裝:


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

設定和使用外掛程式：


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")

AgentCore 付款外掛程式會自動攔截 x402 付款請求、處理付款，並使用代理的付款證明重試請求。

LangGraph

AgentCore 付款中介軟體可為 LangGraph 代理程式提供自動付款處理。它支援 x402 Payment Required 通訊協定，可讓客服人員自動處理 HTTP 402 回應。

安裝:


pip install 'bedrock-agentcore[langgraph]'

設定和使用中介軟體：


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)

AgentCore 付款中介軟體會自動攔截 x402 付款請求、處理付款，並使用代理程式的付款證明重試請求。

支付 x402 付款請求

當商家在其回應中以 x402 付款承載402 Payment Required回應時，您可以將該承載轉送至 AgentCore 付款，而 AgentCore 付款會傳回已簽署的證明。您可以將商家的承載複製到 paymentInput.cryptoX402，而 AgentCore 付款會檢查預算、使用錢包簽署交易，並傳回已簽署的證明。您可以將證明連接到 X-PAYMENT標頭，然後重試原始請求。

請求與回應

在中提供下列欄位paymentInput.cryptoX402：

version — x402 通訊協定版本（例如 1或 2)。必要.
payload — 商家的 x402 付款要求，以 JSON 物件形式傳遞。這會指定商家402回應中的 scheme、network、payTo、、 maxAmountRequired asset和其他欄位。必要.
permit2AllowanceLimit — 在資產的最小面值中，要授予的最大鏈上 Permit2 額度。選用。僅針對透過 Permit2 合約達成和解的 upto（計量）方案設定此項目；為exact方案提供此項目是驗證錯誤。請參閱最多筆付款的 Permit2 額度。

回應會在中傳回下列欄位paymentOutput.cryptoX402：

version — x402 通訊協定版本。
payload — 已簽署的交易證明，做為 JSON 物件。將它連接到 X-PAYMENT標頭，然後重試原始請求。

status 的 PROOF_GENERATED表示交易已簽署，且付款證明包含在中paymentOutput。

結構描述

x402 承載會命名 scheme。AgentCore 付款支援下列機制：

exact — 支付商家承載中指定的固定金額。這是預設配置，不需要處理額度。
upto — 支付最高到上限的計量金額。此方案會透過 Permit2 合約達成和解，因此付款人錢包必須已授予 Permit2 額度。請參閱最多筆付款的 Permit2 額度。

最高付款的 Permit2 額度

upto 該方案透過 Permit2 合約進行和解，該合約會使用轉移資金transferFrom。付款人錢包必須先授予 Permit2 ERC-20 額度，否則和解失敗並顯示 Permit2-allowance先決條件錯誤。此授予會遵循與任何直接 Permit2 核准相同的鏈上核准模型。如需詳細資訊，請參閱 Uniswap 網站上的 Uniswap Permit2 和 GitHub 網站上的 x402 最新結構描述規格。

若要處理此問題，請將 permit2AllowanceLimit設定為資產最小面值中的最大額度（例如， 1000000 = 1 USDC 和 6 個小數位數）。若要授予無限額度，請以字串傳遞uint256最大值：115792089237316195423570985008687907853269984665640564039457584007913129639935。當您設定此欄位時，AgentCore 付款會在簽署之前提交鏈上approve交易。此交易會產生從錢包原生權杖餘額支付的區塊鏈網路（瓦斯）費用。

因為 approve會設定錢包的額度，而不是新增至該額度，permit2AllowanceLimit所以只有在錢包需要核准（例如，其第一次upto付款）時才會設定，以避免備援的鏈上交易。省略欄位以完全略過額度處理。此欄位僅適用於upto方案；為exact方案提供它是一種驗證錯誤。

下列範例會處理upto付款，並授予 1 USDC 的額度給 Permit2。對於 upto，會maxAmountRequired承載商家在其402回應中公告的上限，並且extra.facilitatorAddress是來自相同回應的和解協調者。

範例

限制

permit2AllowanceLimit 欄位僅適用於 upto配置。為exact配置提供它會傳回 ValidationException。

如需 x402 付款請求驗證錯誤及其解決方法，請參閱 x402 付款請求錯誤。如需付款處理錯誤及其解決方法，請參閱付款處理錯誤。

支付 MPP 挑戰

當商家在其402 Payment Required回應中傳回WWW-Authenticate: Payment挑戰時，請在中逐字轉送挑戰paymentInput.mpp。AgentCore 付款會剖析挑戰、檢查預算、使用錢包簽署，並傳回ready-to-send的Authorization標頭值。AgentCore 付款會處理標頭剖析、Base64url 解碼和簽署，因此您不需要執行這些操作。

請求與回應

在中提供下列欄位paymentInput.mpp：

version — MPP 通訊協定版本（例如 1)。必要.
wwwAuthenticateHeaders — 來自商家402回應的原始WWW-Authenticate: Payment標頭值，逐字傳遞。僅提供一個標頭。必要.
buyerPaysGasFees — 賣方未贊助時，是否授權從買方錢包支付區塊鏈網路（瓦斯）費用。選用。省略或false表示買方拒絕。請參閱網路費用同意。

回應會在中傳回下列欄位paymentOutput.mpp：

version — MPP 通訊協定版本。
selectedPaymentId — AgentCore 支付的挑戰id的，回應了輸入挑戰，因此您可以在不解碼登入資料的情況下關聯結果。
paymentCredential — ready-to-sendAuthorization標頭值，格式為 Payment <base64url-token>。將它做為 Authorization 標頭連接，然後重試原始請求。

重要

請勿解碼或修改 paymentCredential。它會嵌入原始挑戰和已簽署的承載，而商家的 HMAC 會繫結到這些確切的位元組。連接傳回的值。

下列範例會處理 MPP 挑戰。在中逐字設定--payment-type "MPP"和轉送商家WWW-Authenticate: Payment的挑戰 paymentInput.mpp.wwwAuthenticateHeaders（確切是一個標頭）。

範例

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()),
)

回應：


{
    "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"
}

status 的 PROOF_GENERATED表示登入資料已簽署，並包含在中paymentOutput.mpp.paymentCredential。

方法和字符

MPP 挑戰會命名付款 method。AgentCore 付款支援以下charge意圖方法：

evm — 僅限正式 USDC。挑戰必須包含 methodDetails.chainId和 realm。
tempo — 任何 Tempo 鏈，由 methodDetails.chainId使用網路辨識的 USDC 對等字符選取。
solana — mainnet和 devnet 網路，僅收取伺服器贊助費用。

付款工具的區塊鏈網路必須符合挑戰方法。供應商支援取決於連接器類型：

Method	Coinbase CDP	條紋（私有）
`evm`	支援	支援
`tempo`	支援	支援
`solana`	不支援	支援

網路費用同意

區塊鏈網路（瓦斯）費用與挑戰金額不同。挑戰會公告誰透過其methodDetails.feePayer旗標贊助他們：

methodDetails.feePayer=true — 賣方贊助網路費用。 buyerPaysGasFees 沒有作用。
methodDetails.feePayer=false 或不存在 — 除了付款金額之外，買方還會從付費錢包支付網路費用。由於挑戰金額中看不到該成本，AgentCore 付款只會在您設定時簽署buyerPaysGasFees=true；否則會傳回 ValidationException。對於 tempo方法，每當賣方不贊助費用時，都需要此同意。

該evm方法不需要費用同意，因為主持人廣播交易並支付瓦斯費。此solana方法目前僅支援伺服器贊助費用。

限制

AgentCore 付款每次ProcessPayment呼叫只滿足一個挑戰。在中提供單一標頭wwwAuthenticateHeaders。
僅支援charge意圖和提取模式。
MPP 挑戰是短期的。如果挑戰已過期，AgentCore 付款會傳回 ValidationException，而且不會耗用預算。再次請求付費資源以取得新的挑戰，然後重試。

如需 MPP 挑戰驗證錯誤及其解決方法，請參閱 MPP 挑戰錯誤。

架構整合

如需完整的參考文件，包括錯誤處理、組態選項和內建工具，請參閱架構整合。

架構	整合類型	參考資料
Strands 代理程式	外掛程式（以勾點為基礎）	中斷處理、組態選項、內建工具
LangGraph	中介軟體（包裝工具呼叫）	錯誤回呼、允許清單、非同步支援、組態選項

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

連線至 Bazaar

架構整合

處理付款

提示

範例

支付 x402 付款請求

請求與回應

結構描述

最高 付款的 Permit2 額度

範例

限制

支付 MPP 挑戰

請求與回應

重要

範例

方法和字符

網路費用同意

限制

架構整合

最高付款的 Permit2 額度