Saltar al contenido principal
Crea o actualiza una sesión de pago para un pedido Pending. La acción de pago accederá al canal de pago y podría cambiar el estado del pedido; antes de llamar, debes confirmar el ID del pedido, el importe y el método de pago.

Resumen de la interfaz

Límites del pago anónimo

El acceso anónimo se utiliza para escenarios en los que la sesión se pierde después de abrir un enlace de pago copiado, y no requiere ni debe llevar un Account Token de larga duración. Las llamadas anónimas:
  • solo permiten métodos de pago de redirección alojada configurados por el servidor;
  • utilizan de forma fija la página de pago de escritorio;
  • no pueden reclamar pedidos de precio cero;
  • están sujetas a limitación de frecuencia por IP y por pedido;
  • devuelven una proyección mínima del pedido, sin incluir cuenta, Application ni metadata interna.
Los llamadores autenticados deben ser el propietario del pedido o un superadministrador. Los métodos que requieren contexto de usuario, como X402 y el canje de recompensas, no pueden llamarse de forma anónima.

Ejemplo de solicitud

Métodos de pago que requieren autenticación:
pay_way utiliza valores reales compatibles con el modelo de pedido, por ejemplo WechatPay, AliPay, Stripe, Card, Airwallex, X402, PayPal, AppleIAP, Reward, BankTransfer. No todos los valores están disponibles para solicitudes anónimas o para cada sitio.

Descripción de la respuesta

La respuesta exitosa es el objeto de pedido actualizado, que normalmente proporciona el punto de entrada del siguiente paso mediante pay_url; los distintos métodos de pago también pueden devolver, en campos controlados, la información necesaria para que el cliente continúe el pago. La respuesta anónima utiliza una lista blanca mínima de campos, mientras que el propietario autenticado obtiene todos los detalles. No dependas de nombres de campos antiguos como payment_url, qr_code_url o payment_method; el contrato actual de Order utiliza pay_url y pay_way.

Transferencia bancaria

Las cuentas personales y empresariales con sesión iniciada pueden usar BankTransfer, sin necesidad de autenticación empresarial. Tanto las transferencias nacionales en RMB como las transferencias internacionales en USD requieren que el importe del pedido sea de al menos 300 USD; el importe pagadero en RMB se basa en el importe mostrado al momento del pago. Antes del pago, puedes consultar las rutas de transferencia y los umbrales de importe disponibles para el pedido actual mediante GET /api/v1/orders/{order_id}/payment-options/. Las transferencias bancarias deben ser iniciadas por el propietario del pedido después de iniciar sesión, y están sujetas a la configuración del canal receptor y al alcance aplicable del plan; las solicitudes anónimas no pueden usarlas.

Compras dentro de la aplicación en iOS

El propietario del pedido con sesión iniciada puede enviar pay_way: "AppleIAP". Esta solicitud actualiza el pedido pendiente de pago según metadata.apple_price del plan seleccionado y elimina los descuentos; no genera cargos, no otorga créditos ni devuelve un enlace de pago. Los pedidos pendientes de pago antiguos deben completar primero este paso y luego iniciar el pago nativo de Apple. Solo se admite un plan Usage con un producto y precio de Apple configurados; los planes no compatibles o los pedidos por lotes devuelven 400. Después del pago nativo de Apple, envía transaction_id mediante /api/v1/orders/{id}/apple-verify/ para completar la verificación del servidor y la emisión de créditos. La cantidad de créditos proviene del plan; el importe utiliza el precio preestablecido independiente de Apple en USD, sin acumular descuentos de membresía ni recargos del sitio, y el importe del cargo en moneda local para otras regiones se basa en la página de confirmación de Apple.

Errores y reintentos

  • El pedido no es Pending: devuelve 400; no vuelvas a crear la sesión de pago.
  • No se proporcionó pay_way: los pedidos de importe distinto de cero devuelven 400.
  • Una llamada anónima utilizó un método no permitido o un pedido de precio cero: devuelve 403; inicia sesión y vuelve a intentarlo como propietario.
  • Está autenticado, pero no es el propietario del pedido: devuelve 403.
  • Error del canal de pago: no vuelvas a enviar ciegamente; consulta primero los detalles del pedido y vuelve a intentarlo solo después de confirmar que sigue siendo Pending.

Interfaces relacionadas