Configuración

Configura la librería landapay con variables de entorno o con opciones del cliente: API key, tiempos de espera, reintentos, montos y fechas.

Variables de entorno

La instancia landapay se configura sola con estas variables. Las lee la primera vez que haces una llamada, no al importar la librería.

Variable	Para qué sirve
`LANDAPAY_API_KEY`	API key secreta (lp_sk_test_... o lp_sk_live_...). Obligatoria
`LANDAPAY_WEBHOOK_SECRET`	Secreto de firma de tus webhooks (whsec_...). Obligatorio para recibir webhooks
`LANDAPAY_TIMEOUT`	Tiempo máximo por petición en milisegundos. Por defecto 30000
`LANDAPAY_MAX_RETRIES`	Reintentos automáticos ante errores de red, 429 y 5xx. Por defecto 2

Opciones del cliente

Con new Landapay(options) pasas la configuración en código. Lo que no envíes se sigue leyendo de las variables de entorno.

Cliente con opciones propiasTypeScript

1import Landapay from "landapay";2 3const landapay = new Landapay({4  apiKey: process.env.MI_LLAVE_LANDAPAY,5  webhookSecret: process.env.MI_SECRETO_WEBHOOKS,6  timeout: 10_000,7  maxRetries: 3,8});

Revisa cada opción en la referencia del cliente.

Opciones por llamada

Todos los métodos que llaman a la API aceptan un último argumento opcional con idempotencyKey, timeout y maxRetries, que solo aplican a esa llamada.

Opciones de una sola llamadaTypeScript

1const link = await landapay.paymentLinks.create(2  { title: "Pedido A-1001", amount: 15_000_000 },3  { idempotencyKey: "pedido-A-1001", timeout: 5_000, maxRetries: 0 },4);

Tiempos y reintentos

Cada petición espera hasta 30 segundos. Si se agota el tiempo recibes un ConnectionError con código timeout.
Los errores de red, los 429 y los 5xx se reintentan hasta 2 veces con espera creciente, respetando el header Retry-After.
Los reintentos de una creación usan la misma llave de idempotencia, así que nunca crean duplicados.
Cada API key puede hacer hasta 120 peticiones por minuto. Si lo superas y se agotan los reintentos recibes un RateLimitError.

Nombres de campos

La librería usa camelCase en parámetros y respuestas: redirectUrl, expiresAt, externalId. Las llaves que pones en metadata y customFields se guardan tal cual las escribes.

Cada objeto trae object con su tipo y livemode con el modo en que se creó. Los ids llevan un prefijo según el recurso: plink_, plan_, cus_, sub_, scs_, pay_ y evt_.

Montos

Los montos van en centavos de la moneda, como enteros: 15_000_000 son $150.000 COP. Los montos en USD se cobran en COP con la tasa del día.

Fechas y zona horaria

Las respuestas traen las fechas como texto ISO 8601 en UTC. Al enviar una fecha puedes usar un Date o un texto:

Sin zona horaria se toma como hora de Colombia: 2026-12-31T23:59:59.
Con Z es UTC, cinco horas por delante de Colombia: 2027-01-01T04:59:59Z.
Con un offset explícito: 2026-12-31T23:59:59-05:00.

Enviar fechasTypeScript

1await landapay.paymentLinks.create({2  title: "Preventa",3  amount: 9_900_000,4  expiresAt: "2026-12-31T23:59:59", // hora de Colombia5});6 7await landapay.paymentLinks.create({8  title: "Preventa",9  amount: 9_900_000,10  expiresAt: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000), // en 3 días11});

Tipos de TypeScript

El paquete incluye los tipos de todos los objetos, parámetros y eventos. Impórtalos con import type:

Usar los tiposTypeScript

1import type {2  PaymentLink,3  PlanInterval,4  Subscription,5  SubscriptionCreateParams,6  WebhookEvent,7} from "landapay";8 9function canAccess(subscription: Subscription) {10  return subscription.status === "active" || subscription.status === "trialing";11}