PAYMENT-SIGNATURE, y luego reintenta con la misma solicitud.
La diferencia es que el pago de pedidos pertenece a la API de la plataforma y requiere un token de cuenta; mientras que la llamada directa a la API de IA de x402.acedata.cloud puede usar solo X402, sin requerir API Token.
Preparar el pedido
Ingresa a la consola de Ace Data Cloud, selecciona el pedido que necesitas pagar y registra el ID del pedido. Si todavía no tienes un pedido, puedes crear un pedido pendiente de pago en la página de planes. El precio del pedido prevalece según lo mostrado en la página, y elamount en la respuesta 402 de X402 es la base final para la firma.
Crear un token de cuenta
Las solicitudes de pago de pedidos requieren un token de cuenta. Abre la página de Token de la plataforma, y crea un token con formatoplatform-v1-....
Para las solicitudes posteriores usa:
Activar 402
Primero envía una solicitud sinPAYMENT-SIGNATURE:
accepts:
x402Version es 2, network usa un identificador CAIP-2, y el campo de importe es amount.
Resultado de ejecución del programa al crear un pedido de 10 Credits y activar 402:
Los siguientes registros de transacciones son muestras históricas probadas bajo la política anterior; los importes y hashes de transacción se conservan tal como estaban. Los nuevos pedidos X402 ya no ofrecen descuentos por método de pago; usa el amount de la respuesta 402 actual como base para la firma y el pago.
- Después de crear correctamente el pedido, el estado es
Pending; en este momento todavía no hay pago en cadena. - La primera solicitud a
pay/no llevaPAYMENT-SIGNATURE, por lo que devuelve HTTP 402. acceptsproporciona simultáneamente Baseexacty Solanaexact; este tutorial selecciona Base posteriormente.- El precio al crear el pedido era
1.26; al pagar durante la antigua política de descuento de pago X402, el importe real firmado y liquidado fue1.2USDC, correspondiente a1200000atomic USDC.
resource aquí es un campo devuelto por el servidor y que participa en la firma; el cliente no debe reescribir por sí mismo el protocolo, la ruta ni el ID de pedido incluidos en él.
Firmar y reintentar
El pago de pedidos puede reutilizar@acedatacloud/x402-client o las funciones de firma de bajo nivel de acedatacloud-x402. A continuación hay un ejemplo de TypeScript:
exact:
status 200indica que la interfaz de pago de pedidos de la plataforma aceptó estaPAYMENT-SIGNATURE.has_x_payment_response Trueindica que el encabezado de respuesta contiene un reciboPAYMENT-RESPONSEcodificado en Base64.settle_header.success=Trueynetwork=baseindican que el Facilitator ha completado el settlement de Base.- El estado final del pedido es
Finished,pay_wayesX402ypay_idescribe el hash de la transacción en cadena. - El evento
Transferen BaseScan muestra que la dirección de pago transfirió1200000USDC atomic a la dirección receptora de la plataforma, es decir,1.2USDC.
Respuesta exitosa y recibo
Después de que el pago del pedido se realiza correctamente, el cuerpo de respuesta contiene la información del pedido. La plataforma también incluirá en el encabezado de respuestaPAYMENT-RESPONSE una settlement response codificada en Base64, cuyos campos comunes después de decodificar incluyen:
Si necesita conciliación, se recomienda guardar simultáneamente el ID del pedido, la dirección de la billetera pagadora,
transaction y el estado final del pedido.
Consideraciones
- El pago del pedido requiere un token de cuenta de la plataforma y no puede completarse únicamente con la firma de la billetera X402.
amountusa USDC atomic units;1200000representa1.2USDC.- No construya por su cuenta la dirección receptora ni la dirección del activo; prevalece
acceptsen la respuesta 402. - Si la misma
PAYMENT-SIGNATUREse envía repetidamente, el Facilitator aplicará protección contra repetición según el nonce.
Respuesta de fallo de pago
El primer HTTP 402 sinPAYMENT-SIGNATURE es un desafío de pago normal y no representa un fallo de pago. Los fallos de verificación o settlement tras la firma aún conservan el error de cadena estándar como respaldo de compatibilidad, y devuelven una estructura de error estable en extensions.acedatacloud.paymentError:
code; los code desconocidos deben recurrir a un fallo de pago genérico. charged es un campo de tres estados: solo devolverá false cuando se rechace explícitamente antes del settlement; la ausencia del campo indica que el estado del cargo es desconocido y no puede interpretarse como “no se ha cobrado”. Una vez que el pedido actual entra en Failed, no puede reintentarse el pedido original; cree un nuevo pedido después de corregir el problema de la billetera.
metadata.x402.last_error y metadata.x402.errors de la lista y los detalles de pedidos conservan el mismo conjunto de code, stage, retryable, charged y params; el texto explicativo público se guarda en reason y el momento en que ocurrió se guarda en timestamp. Por ejemplo, insufficient_token_balance indica que el saldo de USDC en la red seleccionada es insuficiente, y invalid_signature indica que la firma de pago no es válida; volver a leer el pedido no los cambiará por el genérico payment_failed.
No registre ni envíe la PAYMENT-SIGNATURE completa, firmas de billetera, payload de autorización, diagnósticos originales del Facilitator ni respuestas RPC. Para la investigación de atención al cliente solo se necesitan el ID del pedido y el code de error público.
Recompra y quema de ACE para pagos de Base y Solana
Después de habilitar la estrategia de recompra, el 3% de los importes efectivamente recibidos de Circle USDC de la red principal de Base y USDC de la red principal de Solana que cumplan los requisitos se utiliza para comprar y quemar ACE, sin realizar cargos adicionales a la billetera pagadora. Se provisiona una vez durante la recarga; posteriormente, usar estos Credits para llamar a la API no genera una provisión repetida; los pedidos históricos con descuento y los pedidos con estrategias antiguas no reciben provisiones retroactivas automáticamente. Los pagos de Base conservan el recibo de pago en la cadena Base, mientras que la compra y quema de ACE se ejecutan de forma asíncrona en Solana. Los pagos que cumplen los requisitos provisionan exactamente el 3% según el importe efectivamente recibido, sin un límite fijo por transacción o diario para el monto de recompra; los fondos disponibles, las cotizaciones de mercado y las confirmaciones en cadena aún pueden afectar el tiempo de finalización. El objetoace_burn en los detalles del pedido proporciona settlement_network, settlement_transaction y execution_network, y proporciona swap_signature y burn_signature después de la finalización. Pending o Processing no indican que ya se haya quemado; solo Completed representa que la prueba final en cadena ha sido verificada. Cuando un pago de Base aún no ha alcanzado la confirmación final, la recompra esperará la confirmación, pero no afectará los Credits ya acreditados.
