处理付款

要处理付款，您需要两个资源：

支付工具 — 带有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

选择与卖家paymentType在402 Payment Required响应中使用的协议相匹配的。有关 x402 请求和回复的详细信息，请参阅支付 x402 付款请求。有关 MPP 请求和回复的详细信息，请参阅支付 MPP 质询。

提示

您可以使用 AWS 代理工具包中的 AgentCore 付款技能自动执行此页面上的步骤。该技能是 aws-agents 插件的一部分，它允许 AI 编码代理使用 agentcore CLI 创建您的支付管理器、连接器、凭证提供商、支付工具和会话，并为您的代理添加流程付款工具。有关详细信息，请参阅上的 GitHub 快速入门和AWS 代理工具包。

有五种调用 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 v0.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"
}

a status of PROOF_GENERATED 表示交易已签署，付款凭证已包含在内paymentOutput。

要了解如何paymentInput为每种协议构建，包括 MPP AWS SDK 示例及其响应，请参阅支付 x402 付款请求和支付 MPP 质询。

Strands SDK

AgentCore 付款插件为Strands代理提供自动付款处理。它支持 x402 需要付款协议，使代理能够自动处理 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 需要付款协议，使代理能够自动处理 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回复payTo中的schemenetworkmaxAmountRequiredasset、、、、和其他字段。必需。
permit2AllowanceLimit— 以资产的最小面额发放的最大链上Permit2限额。可选。仅为通过 Permit2 合约结算的upto（计量的）方案设置此项；为该exact方案提供此项是验证错误。参见 Permit2 补贴以了解最高付款金额。

该响应在中返回以下字段paymentOutput.cryptoX402：

version— x402 协议版本。
payload— 签名的交易证明，作为 JSON 对象。将其附加到标X-PAYMENT头并重试原始请求。

a status of PROOF_GENERATED 表示交易已签署，且其中包含付款凭证paymentOutput。

计划

x402 的有效载荷名为 a。scheme AgentCore 付款支持以下方案：

exact— 支付商家有效载荷中指定的固定金额。这是默认方案，不需要处理余额。
upto— 按计量支付金额，最高限额为上限。该计划通过Permit2合同达成和解，因此付款人的钱包必须已经发放了Permit2津贴。参见 Permit2 补贴以了解最高付款金额。

Permit2 补贴，最多可付款

该upto计划通过Permit2合约结算，该合约转移资金。transferFrom付款人钱包必须首先向Permit2发放 ERC-20 津贴，否则结算会因先决条件错误而 Permit2-allowance 失败。该补助金遵循与任何直接的Permit2批准相同的链上批准模式。有关更多信息，请参阅 Uniswap 网站上的 Uniswap Permit2 和网站上的 x402 upto 方案规范。 GitHub

要处理此问题，permit2AllowanceLimit请将资产的最小面额设置为最大额度（例如，1000000= 1 USDC，以小数点后 6 位）。要授予无限额度，请将最大uint256值作为字符串传递：115792089237316195423570985008687907853269984665640564039457584007913129639935。当您设置此字段时， AgentCore 支付会在签名之前提交链上approve交易。该交易会产生从钱包的原生代币余额中支付的区块链网络（汽油）费用。

因为approve只有在钱包需要批准（例如，首次upto付款）时，permit2AllowanceLimit才会设置钱包的配额，而不是增加钱包的配额，以避免冗余的链上交易。省略该字段可完全跳过津贴处理。此字段仅适用于upto方案；为该exact方案提供该字段是验证错误。

以下示例处理upto付款并向 Permit2 发放 1 USDC 的津贴。因maxAmountRequired为upto，承担了商家在回应中宣传的上限，并且extra.facilitatorAddress是同一402回应的结算促进者。

例

限制

该permit2AllowanceLimit字段仅对该upto方案有效。为该exact计划提供它会返回 aValidationException.

有关 x402 付款请求验证错误及其解决方法，请参阅 x402 付款请求错误。有关付款处理错误及其解决方法，请参阅付款处理错误。

支付 MPP 挑战赛

当卖家在回402 Payment Required复中返回WWW-Authenticate: Payment挑战时，逐字转发挑战。paymentInput.mpp AgentCore payments 解析挑战，检查预算，使用钱包签名，并返回准备发送的标头Authorization值。 AgentCore 付款负责处理标头解析、base64url 解码和签名，因此您无需执行这些操作。

请求和响应

在中提供以下字段paymentInput.mpp：

version— MPP 协议版本（例如，1）。必需。
wwwAuthenticateHeaders— 来自商家402回复的原始WWW-Authenticate: Payment标题值，逐字传递。只提供一个标题。必需。
buyerPaysGasFees— 当卖方不赞助时，是否授权从买方的钱包中支付区块链网络（汽油）费用。可选。省略或false表示买家拒绝。请参阅网络费用同意。

该响应在中返回以下字段paymentOutput.mpp：

version— MPP 协议版本。
selectedPaymentId— AgentCore 付款支付id的挑战之一与输入挑战相呼应，因此您无需解码凭证即可关联结果。
paymentCredential— 表单中的准备发送Authorization标头值。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"
}

o status f PROOF_GENERATED 表示该凭证已签名并包含在中。paymentOutput.mpp.paymentCredential

方法和标记

MPP 质询将付款命名为付款method。 AgentCore 付款支持以下charge意图方法：

evm— 仅限权威的 USDC。挑战必须包括methodDetails.chainId和realm。
tempo— 使用网络公认的 USDC-equivalent 代币选择的methodDetails.chainId任何 Tempo 链。
solana— mainnet 和devnet网络，仅收取服务器赞助的费用。

支付工具的区块链网络必须与质询方法相匹配。提供商支持取决于连接器类型：

方法	Coinbase CDP	条纹（Privy）
`evm`	支持	支持
`tempo`	支持	支持
`solana`	不支持	支持

网络费用同意

区块链网络（汽油）费用与挑战金额是分开的。挑战赛通过methodDetails.feePayer旗帜宣传谁赞助他们：

methodDetails.feePayer=true— 卖方赞助网络费用。buyerPaysGasFees没有效果。
methodDetails.feePayer=false或缺席 — 除了付款金额外，买家还要从付款钱包中支付网络费用。由于该费用在挑战金额中不可见，因此只有在您设置了 AgentCore 付款时才会签buyerPaysGasFees=true名；否则返回 a ValidationException。对于该tempo方法，只要卖方不支付赞助费，就必须征得同意。

该evm方法无需费用同意，因为协调人会广播交易并支付汽油费。该solana方法目前仅支持服务器赞助的费用。

限制

AgentCore 每次ProcessPayment通话付款只能满足一项挑战。在中提供单个标题wwwAuthenticateHeaders。
仅支持 charge intent 和 pull 模式。
MPP 挑战是短暂的。如果挑战已到期，则 AgentCore 付款将返回 a ValidationException 且不会消耗任何预算。再次请求付费资源以获得新的挑战，然后重试。

有关 MPP 质询验证错误及其解决方法，请参阅 MPP 质询错误。

框架集成

有关包括错误处理、配置选项和内置工具在内的完整参考文档，请参阅框架集成。

框架	集成类型	参考
Strands 代理商	插件（基于挂钩）	中断处理、配置选项、内置工具
LangGraph	中间件（包装工具调用）	错误回调、允许列表、异步支持、配置选项

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

连接到 Bazaar

框架集成