API de enlaces de pago y claves de API

Una solicitud de servidor devuelve un enlace listo#

POST /api/v1/payments y /api/v1/payment-links crean el mismo tipo de factura. El nombre de la ruta payments no implica un cargo: el resultado son términos de factura persistidos y una checkoutUrl para el cliente.

Envíe Authorization: Bearer <key>, Content-Type: application/json y Idempotency-Key. Las claves de idempotencia contienen 16–100 letras, dígitos, guiones o guiones bajos. Persista una clave para cada creación lógica de pedido.

curl 'https://kevmi.maxeevmax1.chatgpt.site/api/v1/payments' \
  -H "Authorization: Bearer $KEVMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-create-v1' \
  --data '{"title":"Design project · order 1042","description":"One-time payment for the agreed design work","amountMinor":500,"currency":"USD","methods":["card","alipay"],"vatCustomerPercent":100,"feeCustomerPercent":0,"orderId":"order-1042","metadata":{"campaign":"autumn"}}'

Alcances y caducidad de las claves de API#

Cree una clave en /account#keys en su cuenta de comerciante verificada. Su valor completo aparece una sola vez; solo se almacena un hash. Las claves duran 90 días de forma predeterminada, con una vida útil permitida de 1–365 días y hasta diez claves activas por cuenta.

Otorgue únicamente los alcances necesarios. La revocación o caducidad detiene el acceso. Una clave no reemplaza la sesión del navegador para la configuración de la cuenta, la administración de endpoints, las aplicaciones o la moderación. Manténgala fuera de widgets, URL, repositorios públicos y mensajes de soporte.

El sitio web usa /api/payment-links con su cookie de sesión, Origin exacto y X-CSRF-Token. Esas rutas operan sobre las mismas facturas propiedad de la cuenta.

Any y métodos de API concretos#

Any es un modo de selección de interfaz. Las facturas nuevas aceptan métodos: ["card", "alipay"] o un subconjunto no vacío para USD; ["sbp"] para RUB; ["crypto"] para USDT. El valor any no es un método de pago de API.

Para una factura nueva en la interfaz, USD ofrece tarjetas y Alipay; RUB ofrece SBP; USDT ofrece criptomonedas. La API también puede guardar USD + criptomonedas por compatibilidad, pero su pago cripto en vivo está bloqueado con crypto_requires_usdt. USD y USDT son distintos, sin conversión automática ni supuesta tasa 1:1. Un pago cripto requiere una factura USDT separada.

Para un pago nuevo en vivo con tarjeta o Alipay, la pasarela actual solo admite feeCustomerPercent=0 y vatCustomerPercent=100: el comerciante cubre toda la comisión de procesamiento y el IVA se añade completo para el cliente. Otras participaciones se pueden guardar y calcular en una factura, pero la ejecución está bloqueada con unsupported_allocation. El servidor nunca cambia silenciosamente los términos guardados. Los pagos cripto SBP y USDT admiten todas las participaciones de comisión de procesamiento y no tienen IVA.

Campos y términos persistidos#

La factura guarda el nombre del comerciante, el precio, la moneda, los métodos, ambas participaciones de costo y las cotizaciones calculadas. Los metadatos se devuelven al propietario y en los eventos del servidor, pero no a través del checkout público. No almacene secretos de pago en ellos.

Si se omiten las participaciones, el comerciante cubre la tarifa; el IVA hereda vatPayer o la configuración de la cuenta. Una asignación parcial puede devolver vatPayer=shared. El título, orderId y description son públicos.

Reintente después de un error de red#

La creación inicial devuelve 201 con replayed=false. La misma clave y cuerpo canónico devuelven 200, la checkoutUrl original y replayed=true. Una solicitud diferente con esa clave devuelve 409 IDEMPOTENCY_CONFLICT.

No genere otra clave después de un tiempo de espera. Repita la solicitud original con campos idénticos. Los valores omitidos no heredan configuraciones cambiadas de nuevo. orderId ayuda a correlacionar un pedido pero no reemplaza Idempotency-Key y no se requiere que sea único en el almacenamiento.

Lectura y paginación#

GET /api/v1/payments devuelve links y nextCursor; GET /api/v1/payments/{id} devuelve un enlace propio. Se requiere invoices:read. El tamaño de página predeterminado es 30; limit acepta 1–100.

Las respuestas de lista y detalle de GET incluyen link.payment: un resumen de la operación relacionada, o null cuando no existe ninguna operación. Las respuestas POST/PATCH pueden omitirlo; lea la factura de nuevo cuando necesite el resumen. El estado del enlace describe por separado si un pago nuevo puede comenzar. Los campos de tarjeta y las claves privadas nunca se incluyen.

Pase nextCursor sin cambios a través de URLSearchParams. null marca el final; los ID desconocidos y los de otros comerciantes devuelven 404.

GET /api/v1/payments?limit=30
Authorization: Bearer <server-side key>

Pausar, reanudar y cancelar#

PATCH /api/v1/payments/{id} con invoices:write acepta solo {"status":"active"}, {"status":"paused"} o {"status":"cancelled"}. La cancelación es definitiva. expired se deriva del tiempo de caducidad; una factura caducada no puede extenderse.

El precio, las participaciones de costo, la descripción, orderId, los metadatos y la caducidad son inmutables. Cree otra factura para términos diferentes. Cambiar la disponibilidad emite invoice.updated, no un evento de pago exitoso.

La respuesta del cliente#

GET /api/checkout/{token}?method=card devuelve la factura pública, la cotización, la disponibilidad del método y la operación existente. Los metadatos, secretos y saldos del propietario no se exponen.

POST /api/checkout/{token}/pay requiere el Origin del sitio y un método concreto. Los datos de tarjeta se aceptan solo como sellados: {intent,jwe}, después de que el navegador obtenga /card-intent. Los códigos bancarios están cifrados y se envían a través de /code. Crypto usa una factura USDT guardada y un par moneda/red disponible.

Un nuevo pago e intento de tarjeta requieren que la última solicitud de revisión web del comerciante esté aprobada. La aprobación por sí sola no conecta la pasarela de pago. Si la revisión cambia después del envío, la operación existente permanece disponible para lecturas de estado, conciliación y un código bancario solicitado.

Una conexión en vivo faltante devuelve GATEWAY_NOT_CONNECTED; una asignación incompatible nunca se reemplaza con otro cálculo. El estado y reconcile leen la operación original sin un cargo duplicado.

Múltiples tiendas y un precio base en USD#

Elija Todas las tiendas para análisis y operaciones agregados, o seleccione una tienda para sus propios registros. Cada tienda tiene un storeId, nombre, IVA predeterminado, facturas, claves de API, endpoints de webhook, historial de eventos y aplicación web separados. Las notificaciones y tickets de soporte pertenecen a la cuenta. Una cuenta puede crear hasta 100 tiendas. Los registros existentes permanecen en su primera tienda.

Las facturas del nuevo espacio de trabajo usan pricingMode="universal" y un precio base en USD. Any incluye tarjeta, alipay, sbp y cripto; un comerciante puede seleccionar un subconjunto. Tarjetas y Alipay cobran en USD. SBP cobra en RUB usando el tipo de referencia USD/RUB del Banco de Rusia. Cripto cobra USDT bajo la regla explícita de factura 1 USD = 1 USDT. Esta es una regla de conversión de factura, no una cotización de mercado de USDT. La pasarela proporciona la tasa de la moneda seleccionada, el monto exacto de transferencia y las instrucciones antes de la transferencia.

El tipo de referencia y ambos montos se congelan al crear. Las facturas que implican conversión de RUB vencen dentro de 24 horas. Si no se puede obtener el tipo de referencia, la creación falla con FX_UNAVAILABLE; no se usa ningún tipo de respaldo inventado o desactualizado. El monto en minor del propietario y las cotizaciones usan la moneda contable USD. quotes[method].settlement contiene la cotización de cargo nativa. El checkout público expone la moneda de cargo seleccionada en currency, el precio original en baseAmountMinor/baseCurrency y el tipo de referencia en fx. Una vez que un pago ha sido despachado, su método no se puede cambiar; una factura tiene una operación de pasarela.

Cree una clave de API dentro de la tienda prevista y envíe Authorization: Bearer <key> desde su servidor. Su vinculación a tienda es inmutable; X-Kevmi-Store no puede otorgarle acceso a otra tienda. Las sesiones del navegador seleccionan X-Kevmi-Store: <storeId>; omitirlo selecciona la primera tienda. El valor all solo es aceptado por GET /api/account/dashboard y GET /api/payment-links. Las mutaciones requieren una tienda seleccionada, Origin y X-CSRF-Token. Los IDs de cuenta y los IDs de tienda son identificadores diferentes.

Por compatibilidad, las solicitudes de API sin pricingMode="universal" conservan el precio nativo y las restricciones de moneda originales. Las facturas existentes nunca se recalculan. Los recibos confirmados en análisis reflejan pagos verificados menos gastos de factura guardados; no son un saldo retirable. Las monedas de factura heredadas permanecen separadas y los pagos se gestionan con soporte. Cumpla un pedido solo después de verificar payment.fulfillmentReady=true y payment.status="succeeded" a través de la API del servidor, el historial de eventos o un webhook firmado.