SDK de servidor

Paymos mantiene SDK oficiales de servidor para ocho ecosistemas de lenguaje. Todos cubren el mismo contrato: facturas, retiros, canales de pago, depósitos de canal, saldos, hora del servidor, paginación por cursor, errores, reintentos, firma de peticiones y verificación de webhooks.

Los ocho se publican en el registro de paquetes de su lenguaje. Instala desde ahí; el repositorio sigue siendo donde se lee el código fuente.

Lenguaje	Publicado en	Instalación	Repositorio oficial
JavaScript / TypeScript	npm	npm i @paymos/sdk	Paymos-labs/typescript-sdk
Python	PyPI	pip install paymos-sdk	Paymos-labs/python-sdk
PHP	Packagist	composer require paymos/php-sdk	Paymos-labs/php-sdk
Go	Go modules	go get github.com/Paymos-labs/go-sdk/v2	Paymos-labs/go-sdk
.NET	NuGet	dotnet add package Paymos	Paymos-labs/dotnet-sdk
Java	Maven Central	io.paymos:paymos-java	Paymos-labs/java-sdk
Ruby	RubyGems	gem install paymos	Paymos-labs/ruby-sdk
Rust	crates.io	cargo add paymos	Paymos-labs/rust-sdk

Java no tiene un comando de una línea: añade la dependencia io.paymos:paymos-java a tu pom.xml o a tu configuración de Gradle.

Fija una etiqueta de versión inmutable vMAJOR.MINOR.PATCH. La página de releases de cada repositorio indica el runtime admitido, el registro de cambios y el commit de origen a partir del cual se generó la versión.

Superficie común de la API

Todos los clientes exponen seis recursos:

• —system — obtener la hora del servidor para alinear el reloj de las peticiones
• —invoices — crear, obtener, listar, cancelar, confirmar el pago y simular en Sandbox
• —withdrawals — crear, obtener, listar, cancelar y simular la finalización en Sandbox
• —paymentChannels — crear, obtener, listar, bloquear, desbloquear y simular un depósito en Sandbox
• —paymentChannelDeposits — obtener un depósito y consultar el feed de depósitos confirmados
• —balances — listar los saldos disponibles agrupados por moneda

Cada cliente escribe los dos recursos de canal con la convención de su lenguaje: paymentChannels en TypeScript, PHP y Java, payment_channels en Python, Ruby y Rust, y PaymentChannels en Go y .NET.

Los métodos de listado usan paginación por cursor con un límite máximo de página y rechazan un cursor devuelto dos veces. Los reintentos automáticos respetan Retry-After; las peticiones que modifican estado no se reintentan ante errores de transporte ni errores genéricos de servidor. Una petición frenada por el límite de peticiones sí puede reintentarse, porque la API no llegó a aceptarla para su procesamiento.

Un solo contrato para ocho lenguajes

Lo compartido no es solo la lista de endpoints: también el comportamiento. Un único banco de pruebas, independiente del lenguaje, fija qué bytes entran en la firma de una petición, cómo funcionan los reintentos de arriba, cómo recorren las páginas los iteradores de cursor y cómo se verifica un webhook. Una versión sale solo cuando las pruebas del propio SDK se ejecutan contra ese banco.

En la práctica: si te llevas una integración de uno de estos lenguajes a otro, conservas la firma, el recorrido de páginas, los reintentos y el trato de los webhooks. Dos SDK firman con los mismos bytes la misma petición de listado filtrada.

Lo que solo trae PHP

El SDK de PHP incorpora una capa de integración con tiendas que no existe en ningún otro cliente: contraverificación de un webhook contra una lectura fresca de la API, control del importe y la moneda antes de liberar un pedido, descarte de eventos repetidos sobre un almacén intercambiable, un verificador que sostiene a la vez el secreto de Sandbox y el de producción, una conciliación, un mapeo de evento a acción sobre el pedido y almacenamiento cifrado de credenciales.

Esa capa es la razón de que los plugins de CMS sean tan finos: la lógica de estados del pedido vive una sola vez en el SDK que tienen debajo, y no ocho veces encima. A los otros siete no les aplica nada de esto: son cliente, firma, recursos, paginación y verificación de webhooks, y ahí se acaba.

Reglas de seguridad

La autenticación de las peticiones y la de los webhooks usan firmas distintas. Las peticiones a la API usan HMAC-SHA256 en base64 sobre la petición canónica. Los webhooks usan HMAC-SHA256 en hexadecimal sobre {timestamp}.{cuerpo bruto exacto}. Pasa al verificador del SDK los bytes de la petición sin procesar, antes de decodificar el JSON. Por defecto rechaza una marca temporal que se aleje más de cinco minutos del momento actual, y admite una cabecera con dos valores v1, de modo que una rotación del secreto no te cuesta ningún cambio de código.

Para los esquemas y ejemplos de cada endpoint, continúa con Autenticación, Facturas, Retiros, Saldos y Webhooks.