Pague una solicitud de pago x402 Paga un desafío de MPP Integraciones con marcos

Procesar un pago

Para procesar un pago, necesita dos recursos:

Instrumento de pago: un monedero criptográfico integrado con Coinbase o Stripe. Consulta Crear un instrumento de pago.
Sesión de pago: sesión con un límite de tiempo que, de manera opcional, impone un presupuesto de gastos. Consulte Crear una sesión de pago.

Cuando ambos existan, llama ProcessPayment con el identificador de la sesión de pago, el identificador del instrumento de pago y la carga útil del pago. El servicio valida la solicitud, comprueba el presupuesto, firma la transacción en la cadena de bloques correspondiente y devuelve un resultado de pago firmado. Para ver el esquema completo de solicitud y respuesta, consulta la referencia ProcessPayment de la API.

AgentCore payments admite dos protocolos de pago, que puedes seleccionar con el paymentType parámetro:

CRYPTO_X402— El protocolo x402. Introduce la carga útil del pago x402 del vendedor y el agente volverá a intentar la solicitud con el comprobante firmado en el encabezado. paymentInput.cryptoX402 X-PAYMENT
MPP— El protocolo de pagos automáticos (MPP). Reenvía la WWW-Authenticate: Payment impugnación del vendedor y el agente vuelve a intentar la solicitud con la credencial devuelta en el encabezado. paymentInput.mpp Authorization

Elige el paymentType que coincida con el protocolo que el comerciante usó en su 402 Payment Required respuesta. Para obtener más información sobre la solicitud y la respuesta x402, consulta Cómo pagar una solicitud de pago x402. Para obtener más información sobre la solicitud y la respuesta del MPP, consulta el desafío Pagar un MPP.

sugerencia

Puedes automatizar los pasos de esta página con la habilidad AgentCore Pagos del kit de herramientas para AWS agentes. Esta habilidad forma parte del complemento aws-agents y permite a un agente de codificación basada en inteligencia artificial crear tu gestor de pagos, conector, proveedor de credenciales, instrumento de pago y sesión mediante la agentcore CLI, y añadir una herramienta de procesamiento de pagos a tu agente. Para obtener más información, consulte la guía de inicio rápido y el kit de herramientas para agentes en AWS . GitHub

Hay cinco formas de invocar la API: ProcessPayment

ejemplo

AgentCore CLI

Si su agente está desplegado con las funciones de pago configuradas, invóquelo con el contexto de pago y el interceptor x402 gestionará el procesamiento de los pagos automáticamente:


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

Para usar una sesión explícita en lugar de crear una automáticamente:


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

El complemento x402 del agente desplegado intercepta las respuestas y llamadas ProcessPayment del HTTP 402 y vuelve a intentar la solicitud con pruebas. Requiere la AgentCore CLI v0.19.0 o posterior.

AgentCore SDK

Utilice la PaymentManager clase para generar los encabezados de pago manualmente dentro de cualquier marco de agente:


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_headerscontiene el encabezado del comprobante de pago. Incluye este encabezado cuando vuelvas a intentar enviar la solicitud al terminal de pago. También puedes llamar al process_payment método de PaymentManager para tener más control sobre las entradas.

AWS CLI

En el siguiente ejemplo, se procesa un pago x402 transfiriendo la carga útil del vendedor: 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

Para obtener información sobre cómo crear el protocolo paymentInput para cada protocolo, incluido el ejemplo de la AWS CLI de MPP, consulta Pagar una solicitud de pago x402 y el desafío Pagar un MPP.

AWS SDK

En el siguiente ejemplo, se procesa un pago x402 llamando process_payment con la carga útil del vendedor en: 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()),
)

Respuesta:


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

Un status de PROOF_GENERATED indica que la transacción se firmó y que el comprobante de pago está incluido. paymentOutput

Para obtener información sobre cómo crear el protocolo paymentInput para cada protocolo, incluido el ejemplo del AWS SDK de MPP y su respuesta, consulte Pagar una solicitud de pago x402 y el desafío Pagar un MPP.

Strands SDK

El complemento de AgentCore pagos proporciona un procesamiento de pagos automatizado para los agentes de Strands. Es compatible con el protocolo x402 Payment Required, que permite a los agentes gestionar automáticamente las respuestas HTTP 402.

Installation (Instalación):


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

Configura y usa el complemento:


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

El complemento de AgentCore pagos intercepta automáticamente las solicitudes de pago x402, procesa el pago y vuelve a intentar la solicitud con un comprobante de pago para el agente.

LangGraph

El middleware de AgentCore pagos proporciona un procesamiento de pagos automatizado para los agentes. LangGraph Es compatible con el protocolo x402 Payment Required, que permite a los agentes gestionar automáticamente las respuestas HTTP 402.

Installation (Instalación):


pip install 'bedrock-agentcore[langgraph]'

Configure y utilice el 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)

El middleware de AgentCore pagos intercepta automáticamente las solicitudes de pago x402, procesa el pago y vuelve a intentar la solicitud con un comprobante de pago para el agente.

Pague una solicitud de pago x402

Cuando un vendedor responde con una carga de pago x402 en su 402 Payment Required respuesta, tú reenvías esa carga a Payments y AgentCore AgentCore Payments devuelve un comprobante firmado. Copias la carga útil del comerciante y AgentCore Payments comprueba el presupuestopaymentInput.cryptoX402, firma la transacción con el monedero y devuelve el comprobante firmado. Adjuntas la prueba al X-PAYMENT encabezado y vuelves a intentar la solicitud original.

Solicitud y respuesta

Introduzca los siguientes campos enpaymentInput.cryptoX402:

version— La versión del protocolo x402 (por ejemplo, 1 o2). Obligatorio.
payload— Los requisitos de pago x402 del vendedor, transmitidos como un objeto JSON. Aquí se especifican los campos scheme networkmaxAmountRequired,asset,payTo, y otros campos de la 402 respuesta del vendedor. Obligatorio.
permit2AllowanceLimit— La cantidad máxima que Permit2 puede conceder en la cadena, en la denominación más pequeña del activo. Opcional. Configúralo solo para el sistema upto (medido), que se liquida mediante el contrato Permit2; suministrarlo para el exact sistema es un error de validación. Consulte la asignación de Permit2 para ver los pagos totales.

La respuesta devuelve los siguientes campos en: paymentOutput.cryptoX402

version— La versión del protocolo x402.
payload— La prueba de transacción firmada, como objeto JSON. Adjúntelo al X-PAYMENT encabezado y vuelva a intentar la solicitud original.

Un status de PROOF_GENERATED indica que la transacción se firmó y que se incluye el comprobante de pago. paymentOutput

Esquemas

Una carga útil x402 se denomina a. scheme AgentCore payments admite los siguientes esquemas:

exact— Paga una cantidad fija especificada en la carga útil del comerciante. Este es el esquema predeterminado y no requiere la gestión de las asignaciones.
upto— Paga una cantidad medida hasta un límite máximo. Este plan se liquida mediante el contrato de Permit2, por lo que el monedero del pagador debe haber otorgado una asignación a Permit2. Consulta la asignación de Permit2 para ver los pagos totales.

Asignación Permit2 para hasta pagos

El upto plan se liquida mediante el contrato Permit2, que transfiere fondos con. transferFrom El monedero del pagador debe conceder primero una ERC-20 asignación a Permit2, o la liquidación no se realizará por un error de precondición. Permit2-allowance Esta subvención sigue el mismo modelo de aprobación en cadena que cualquier aprobación directa de Permit2. Para obtener más información, consulte Uniswap Permit2 en el sitio web de Uniswap y la especificación del esquema x402 upto en el sitio web. GitHub

Para solucionar este problema, establezca permit2AllowanceLimit la asignación máxima en la denominación más pequeña del activo (por ejemplo, 1000000 = 1 USDC con 6 decimales). Para conceder una asignación ilimitada, pasa el uint256 valor máximo en forma de cadena:. 115792089237316195423570985008687907853269984665640564039457584007913129639935 Cuando configuras este campo, AgentCore Payments envía una approve transacción en cadena antes de firmarla. Esta transacción implica comisiones de red de cadena de bloques (gas) que se pagan con el saldo de fichas nativo del monedero.

Porque approve establece la asignación del monedero, en lugar de aumentarla, y permit2AllowanceLimit solo se establece cuando el monedero necesita ser aprobado (por ejemplo, su primer upto pago) para evitar una transacción redundante en cadena. Omite este campo para omitir por completo la gestión de las asignaciones. Este campo solo se aplica al upto esquema; introducirlo para el exact esquema constituye un error de validación.

El siguiente ejemplo procesa un upto pago y otorga una asignación de 1 USDC a Permit2. Puesupto, maxAmountRequired lleva el límite máximo que el comerciante anuncia en su 402 respuesta y extra.facilitatorAddress es el facilitador de la liquidación a partir de esa misma respuesta.

ejemplo

Limitaciones

El permit2AllowanceLimit campo solo es válido para el upto esquema. Al suministrarlo para el exact esquema, se devuelve unValidationException.

Para ver los errores de validación de solicitudes de pago x402 y sus soluciones, consulte Errores de solicitudes de pago x402. Para ver los errores de procesamiento de pagos y sus soluciones, consulta Errores de procesamiento de pagos.

Paga un desafío de MPP

Cuando un comerciante devuelva una WWW-Authenticate: Payment impugnación en su 402 Payment Required respuesta, reenvíela textualmente. paymentInput.mpp AgentCore payments analiza la impugnación, comprueba el presupuesto, la firma con el monedero y devuelve un valor de encabezado listo para Authorization enviar. AgentCore payments se encarga del análisis de los encabezados, la decodificación de base64url y la firma, por lo que no es necesario que realices estas operaciones.

Solicitud y respuesta

Introduzca los siguientes campos en: paymentInput.mpp

version— La versión del protocolo MPP (por ejemplo,1). Obligatorio.
wwwAuthenticateHeaders— El valor sin procesar del WWW-Authenticate: Payment encabezado de la 402 respuesta del vendedor, aprobado textualmente. Proporciona exactamente un encabezado. Obligatorio.
buyerPaysGasFees— Si se autoriza el pago de las tarifas de la red blockchain (gas) con cargo al monedero del comprador cuando el vendedor no las patrocine. Opcional. Se omite o false significa que el comprador se niega. Consulta la sección Consentimiento sobre las tarifas de red.

La respuesta devuelve los siguientes campos enpaymentOutput.mpp:

version— La versión del protocolo MPP.
selectedPaymentId— El id desafío que suponía pagar AgentCore los pagos se repitió con el desafío de introducir datos para poder correlacionar el resultado sin necesidad de decodificar la credencial.
paymentCredential— El valor del Authorization encabezado listo para enviar, en el formulario. Payment <base64url-token> Adjúntelo como Authorization encabezado y vuelva a intentar la solicitud original.

importante

No decodifique ni modifique. paymentCredential Incluye el desafío original y la carga útil firmada, y el HMAC del vendedor se vincula a esos bytes exactos. Adjunte el valor devuelto.

El siguiente ejemplo procesa un desafío de MPP. Configura --payment-type "MPP" y reenvía el WWW-Authenticate: Payment desafío del comerciante literalmente en paymentInput.mpp.wwwAuthenticateHeaders (exactamente un encabezado).

ejemplo

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

Respuesta:


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

Un status de PROOF_GENERATED indica que la credencial se firmó y está incluida en. paymentOutput.mpp.paymentCredential

Métodos y fichas

Un desafío del MPP nombra un pagomethod. AgentCore Para ello, Payments admite los siguientes métodoscharge:

evm— Solo el USDC canónico. El desafío debe incluir y. methodDetails.chainId realm
tempo— Cualquier cadena de Tempo, seleccionada pormethodDetails.chainId, utilizando el USDC-equivalent token reconocido de la red.
solana— Las devnet redes mainnet y, solo con tarifas patrocinadas por el servidor.

La red blockchain del instrumento de pago debe coincidir con el método de verificación. La asistencia del proveedor depende del tipo de conector:

Método	Coinbase CDP	Stripe (privado)
`evm`	Soportado	Soportado
`tempo`	Soportado	compatible
`solana`	No compatible	compatible

Consentimiento sobre la tarifa de red

Las tarifas de la red blockchain (gas) son independientes del importe del desafío. Un desafío anuncia quién lo patrocina a través de su methodDetails.feePayer bandera:

methodDetails.feePayer=true— El vendedor patrocina las tarifas de la red. buyerPaysGasFeesno tiene ningún efecto.
methodDetails.feePayer=falseo ausente: el comprador paga las tarifas de la red con el monedero de pago, además del importe del pago. Como ese coste no aparece en el importe del desafío, AgentCore los pagos solo firman si tú lo configurasbuyerPaysGasFees=true; de lo contrario, devuelve unValidationException. En el caso del tempo método, este consentimiento es necesario siempre que el vendedor no patrocine las tarifas.

El evm método no necesita el consentimiento de los honorarios, ya que el facilitador difunde la transacción y paga el gas. En la actualidad, el solana método solo admite tarifas patrocinadas por el servidor.

Limitaciones

AgentCore Los pagos cumplen exactamente un desafío por llamada. ProcessPayment Proporcione un solo encabezado enwwwAuthenticateHeaders.
Solo se admiten los modos de charge intención y extracción.
Los desafíos del MPP son efímeros. Si el desafío ha caducado, AgentCore los pagos se devuelven ValidationException y no consumen ningún presupuesto. Vuelve a solicitar el recurso pagado para obtener un desafío nuevo y vuelve a intentarlo.

Para ver los errores de validación de desafíos de MPP y sus soluciones, consulte Errores de desafío de MPP.

Integraciones con marcos

Para obtener la documentación de referencia completa, que incluye la gestión de errores, las opciones de configuración y las herramientas integradas, consulte Framework Integrations.

Marcos	Tipo de integración	Referencia
Agentes de Strands	Plugin (basado en ganchos)	Gestión de interrupciones, opciones de configuración, herramientas integradas
LangGraph	Middleware (resume las llamadas a las herramientas)	Reversiones de llamadas de error, listas permitidas, soporte asincrónico, opciones de configuración

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Conectarse a Bazaar

Integraciones con marcos