本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 处理付款
<a name="payments-process-payment"></a>

要处理付款，您需要两个资源：
+  **支付工具 ** — 带有Coinbase或Stripe的嵌入式加密钱包。请参阅[创建付款工具](payments-create-instrument.md)。
+  **付款会话 ** — 有时间限制的会话，可以选择强制执行支出预算。请参阅[创建付款会话](payments-create-session.md)。

两者都存在后，`ProcessPayment`使用付款会话 ID、支付工具 ID 和支付负载进行呼叫。该服务验证请求，检查预算，在相应的区块链上签署交易，并返回签名的付款结果。有关完整的请求和响应架构，请参阅 API 参考[ProcessPayment](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)中的。

AgentCore 支付支持两种支付协议，您可以通过以下`paymentType`参数进行选择：
+  `CRYPTO_X402`— x402 协议。提供商家的 x402 付款有效载荷`paymentInput.cryptoX402`，代理商使用标题中的签名证明重试请求。`X-PAYMENT`
+  `MPP`— 机器支付协议 (MPP)。转发卖家的`WWW-Authenticate: Payment`质询`paymentInput.mpp`，代理在标题中使用返回的凭证重试请求。`Authorization`

选择与卖家`paymentType`在`402 Payment Required`响应中使用的协议相匹配的。有关 x402 请求和回复的详细信息，请参阅[支付 x402 付款请求。](#payments-process-payment-x402)有关 MPP 请求和回复的详细信息，请参阅[支付 MPP 质询。](#payments-process-payment-mpp)

**提示**  
您可以使用 Amazon 代理工具包中的 AgentCore 付款技能自动执行此页面上的步骤。该技能是 ** aws-agents ** 插件的一部分，它允许 AI 编码代理使用 `agentcore` CLI 创建您的支付管理器、连接器、凭证提供商、支付工具和会话，并为您的代理添加流程付款工具。有关详细信息，请参阅上的[ GitHub](payments-getting-started.md)[快速入门和](https://github.com/aws/agent-toolkit-for-aws/tree/main)Amazon 代理工具包。

有五种调用 ProcessPayment API 的方法：

**Example**  
如果您的代理部署时配置了支付功能，请在付款上下文中调用它，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 或更高版本。
使用该`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`来更好地控制输入。
以下示例通过传入商家的有效负载来处理 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 ` Amazon ` CLI 示例，请参阅[支付 x402 付款申请](#payments-process-payment-x402)和支付 MPP 质[询。](#payments-process-payment-mpp)
以下示例通过调用`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 ` Amazon ` SDK 示例及其响应，请参阅[支付 x402 付款请求](#payments-process-payment-x402)和支付 MPP 质[询。](#payments-process-payment-mpp)
 AgentCore 付款插件为Strands代理提供自动付款处理。它支持 [ x402 需要付款](https://www.x402.org/)协议，使代理能够自动处理 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付款请求，处理付款，并使用代理的付款证明重试该请求。
 AgentCore 支付中间件为 LangGraph 代理提供自动付款处理。它支持 [ x402 需要付款](https://www.x402.org/)协议，使代理能够自动处理 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 付款申请
<a name="payments-process-payment-x402"></a>

当卖家在回复中使用 x402 的付款有效载荷进行`402 Payment Required`响应时，您将该负载转发给 AgentCore 付款， AgentCore 付款会返回签名的证明。您将商家的有效载荷复制到`paymentInput.cryptoX402`， AgentCore 付款会检查预算，用钱包签署交易，然后返回签名的证明。您将证明附加到`X-PAYMENT`标题中，然后重试原始请求。

### 请求和响应
<a name="_request_and_response"></a>

在中提供以下字段`paymentInput.cryptoX402`：
+  `version`— x402 协议版本（例如，`1`或`2`）。必需。
+  `payload`— 商家的 x402 付款要求，作为 JSON 对象传递。这指定了卖家`402`回复`payTo`中的`scheme``network``maxAmountRequired``asset`、、、、和其他字段。必需。
+  `permit2AllowanceLimit`— 以资产的最小面额发放的最大链上Permit2限额。可选。仅为通过 Permit2 合约结算的`upto`（计量的）方案设置此项；为该`exact`方案提供此项是验证错误。参见 [ Permit2 补贴以了解最高付款金额。](#payments-process-payment-x402-permit2)

该响应在中返回以下字段`paymentOutput.cryptoX402`：
+  `version`— x402 协议版本。
+  `payload`— 签名的交易证明，作为 JSON 对象。将其附加到标`X-PAYMENT`头并重试原始请求。

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

### 计划
<a name="_schemes"></a>

x402 的有效载荷名为 a。`scheme` AgentCore 付款支持以下方案：
+  `exact`— 支付商家有效载荷中指定的固定金额。这是默认方案，不需要处理余额。
+  `upto`— 按计量支付金额，最高限额为上限。该计划通过Permit2合同达成和解，因此付款人的钱包必须已经发放了Permit2津贴。参见 [ Permit2 补贴以了解最高付款金额。](#payments-process-payment-x402-permit2)

### Permit2 补贴，最多可付款
<a name="payments-process-payment-x402-permit2"></a>

该`upto`计划通过Permit2合约结算，该合约转移资金。`transferFrom`付款人钱包必须首先向Permit2发放 ERC-20 津贴，否则结算会因先决条件错误而 Permit2-allowance 失败。该补助金遵循与任何直接的Permit2批准相同的链上批准模式。有关更多信息，请参阅 [ Uniswap 网站上的 Uniswap Permit2 ](https://docs.uniswap.org/contracts/permit2/overview) 和网站上的 [ x402 upto 方案规范。](https://github.com/coinbase/x402/blob/main/specs/schemes/upto/README.md) GitHub 

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

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

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

**Example**  

```
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": "upto",
                "network": "eip155:8453",
                "maxAmountRequired": "3495",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2", "facilitatorAddress": "0x8581784D3E598cCa3482375CFF2409Ac9DD8c402"}
            },
            "permit2AllowanceLimit": "1000000"
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2
```

```
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": "upto",
                "network": "eip155:8453",
                "maxAmountRequired": "3495",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2", "facilitatorAddress": "0x8581784D3E598cCa3482375CFF2409Ac9DD8c402"},
            },
            "permit2AllowanceLimit": "1000000",
        }
    },
    clientToken=str(uuid.uuid4()),
)
```

### 限制
<a name="_limitations"></a>
+ 该`permit2AllowanceLimit`字段仅对该`upto`方案有效。为该`exact`计划提供它会返回 a`ValidationException`.

有关 x402 付款请求验证错误及其解决方法，请参阅 [ x402 付款请求错误。](payments-troubleshooting.md#payments-troubleshooting-x402)有关付款处理错误及其解决方法，请参阅[付款处理错误](payments-troubleshooting.md#payments-troubleshooting-processing)。

## 支付 MPP 挑战赛
<a name="payments-process-payment-mpp"></a>

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

### 请求和响应
<a name="_request_and_response_2"></a>

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

该响应在中返回以下字段`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`（正好只有一个标题）。

**Example**  

```
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
```

```
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`

### 方法和标记
<a name="_methods_and_tokens"></a>

MPP 质询将付款命名为付款`method`。 AgentCore 付款支持以下`charge`意图方法：
+  `evm`— 仅限权威的 USDC。挑战必须包括`methodDetails.chainId`和`realm`。
+  `tempo`— 使用网络公认的 USDC-equivalent 代币选择的`methodDetails.chainId`任何 Tempo 链。
+  `solana`— `mainnet` 和`devnet`网络，仅收取服务器赞助的费用。

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


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

### 网络费用同意
<a name="payments-process-payment-mpp-fees"></a>

区块链网络（汽油）费用与挑战金额是分开的。挑战赛通过`methodDetails.feePayer`旗帜宣传谁赞助他们：
+  `methodDetails.feePayer=true`— 卖方赞助网络费用。`buyerPaysGasFees`没有效果。
+  `methodDetails.feePayer=false`或缺席 — 除了付款金额外，买家还要从付款钱包中支付网络费用。由于该费用在挑战金额中不可见，因此只有在您设置了 AgentCore 付款时才会签`buyerPaysGasFees=true`名；否则返回 a `ValidationException`。对于该`tempo`方法，只要卖方不支付赞助费，就必须征得同意。

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

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

有关 MPP 质询验证错误及其解决方法，请参阅 [ MPP 质询错误。](payments-troubleshooting.md#payments-troubleshooting-mpp)

## 框架集成
<a name="_framework_integrations"></a>

有关包括错误处理、配置选项和内置工具在内的完整参考文档，请参阅[框架集成。](payments-framework-integrations.md)


| 框架 | 集成类型 | 参考 | 
| --- | --- | --- | 
|  [Strands 代理商 ](payments-framework-integrations.md#payments-framework-strands)  | 插件（基于挂钩） | 中断处理、配置选项、内置工具 | 
|  [LangGraph](payments-framework-integrations.md#payments-framework-langgraph)  | 中间件（包装工具调用） | 错误回调、允许列表、异步支持、配置选项 |