wompi-payment-links

name	wompi-payment-links
description	Create, retrieve, and manage Wompi hosted payment links using @pulgueta/wompi. Covers createPaymentLink (name, description, single_use, collect_shipping, amount_in_cents, currency, taxes, customer_data, redirect_url), getPaymentLink (no auth required), updatePaymentLink to activate/deactivate, Tax union (TaxByAmount with amount_in_cents, TaxByPercentage with percentage 1–50), and CustomerReference constraints (max 2, label max 24 chars). Load when building hosted checkout pages or no-code payment collection.
type	core
library	@pulgueta/wompi
library_version	3.0.0
requires	["wompi-client-setup"]
sources	["pulgueta/wompi-node:packages/core/src/client/payment-links/index.ts","pulgueta/wompi-node:packages/core/src/schemas.ts"]

This skill builds on wompi/client-setup. Read it first for key configuration and the error-first tuple pattern.

Setup

import { WompiClient } from '@pulgueta/wompi';

const wompi = new WompiClient({
  publicKey: process.env.WOMPI_PUBLIC_KEY!,
  privateKey: process.env.WOMPI_PRIVATE_KEY!, // required for create/update
  sandbox: process.env.NODE_ENV !== 'production',
});

// Create a single-use payment link with a fixed amount
const [error, link] = await wompi.paymentLinks.createPaymentLink({
  name: 'Orden #12345',
  description: 'Pago de pedido online',
  single_use: true,
  collect_shipping: false,
  amount_in_cents: 2_490_000,
  currency: 'COP',
  redirect_url: 'https://mystore.co/gracias',
});
if (error) throw error;

console.log(link.id, link.active); // 'link_xxx', true

Core Patterns

Multi-use payment link (e.g. donation page)

const [error, link] = await wompi.paymentLinks.createPaymentLink({
  name: 'Donación voluntaria',
  description: 'Apoya nuestra causa',
  single_use: false,   // reusable
  collect_shipping: false,
  // omit amount_in_cents to let the customer enter the amount
});
if (error) throw error;

Payment link with taxes

taxes is an array of TaxByAmount or TaxByPercentage objects — not both fields in the same object.

const [error, link] = await wompi.paymentLinks.createPaymentLink({
  name: 'Producto con IVA',
  description: 'Incluye IVA 19%',
  single_use: true,
  collect_shipping: false,
  amount_in_cents: 1_000_000,
  currency: 'COP',
  taxes: [
    { type: 'VAT', percentage: 19 }, // TaxByPercentage — 1 to 50
    // OR: { type: 'VAT', amount_in_cents: 190_000 } // TaxByAmount
  ],
});
if (error) throw error;

Collect custom customer references

customer_references accepts at most 2 items. Each label has a maximum of 24 characters.

const [error, link] = await wompi.paymentLinks.createPaymentLink({
  name: 'Pago de factura',
  description: 'Ingrese el número de factura',
  single_use: true,
  collect_shipping: false,
  customer_data: {
    customer_references: [
      { label: 'Número de factura', is_required: true },  // max 24 chars
      { label: 'Código cliente',    is_required: false },  // max 2 items total
    ],
  },
});
if (error) throw error;

Retrieve and deactivate a payment link

getPaymentLink requires no authentication. updatePaymentLink requires privateKey and only accepts { active: boolean }.

// Retrieve — no privateKey needed
const [getErr, link] = await wompi.paymentLinks.getPaymentLink('link_123');
if (getErr) throw getErr;
console.log(link.active);

// Deactivate
const [updateErr, updated] = await wompi.paymentLinks.updatePaymentLink('link_123', {
  active: false,
});
if (updateErr) throw updateErr;
console.log(updated.active); // false

Common Mistakes

HIGH Calling createPaymentLink or updatePaymentLink without privateKey

Wrong:

const wompi = new WompiClient({ publicKey: process.env.WOMPI_PUBLIC_KEY! });

const [error] = await wompi.paymentLinks.createPaymentLink({ ... });
// error.message === "Private key is required for payment link operations"
// No HTTP call — returns immediately

Correct:

const wompi = new WompiClient({
  publicKey: process.env.WOMPI_PUBLIC_KEY!,
  privateKey: process.env.WOMPI_PRIVATE_KEY!,
});

getPaymentLink does NOT require privateKey. createPaymentLink and updatePaymentLink do.

Source: packages/core/src/client/payment-links/index.ts

---

MEDIUM Exceeding customer_references array limit or label length

Wrong:

await wompi.paymentLinks.createPaymentLink({
  customer_data: {
    customer_references: [
      { label: 'Este label tiene más de veinticuatro caracteres', is_required: true },
      { label: 'Ref2', is_required: false },
      { label: 'Ref3', is_required: false }, // third item — max is 2
    ],
  },
  // ...
});
// Returns [WompiError, null] — validation fails before HTTP call

Correct:

await wompi.paymentLinks.createPaymentLink({
  customer_data: {
    customer_references: [
      { label: 'Número de factura', is_required: true },  // ≤24 chars
      { label: 'Código cliente',    is_required: false },  // max 2 items
    ],
  },
  // ...
});

Source: packages/core/src/schemas.ts — CustomerReferenceSchema, PaymentLinkCustomerDataSchema

---

MEDIUM Mixing amount_in_cents and percentage in a single Tax object

Wrong:

taxes: [
  { type: 'VAT', amount_in_cents: 190_000, percentage: 19 }, // invalid — pick one
]

Correct:

// TaxByPercentage: use percentage (integer 1–50)
taxes: [{ type: 'VAT', percentage: 19 }]

// TaxByAmount: use amount_in_cents
taxes: [{ type: 'VAT', amount_in_cents: 190_000 }]

// Both tax types in the same link
taxes: [
  { type: 'VAT', percentage: 19 },
  { type: 'CONSUMPTION', amount_in_cents: 50_000 },
]

Tax is a discriminated union — TaxByAmount and TaxByPercentage are mutually exclusive shapes. Providing both fields in one object fails Zod validation.

Source: packages/core/src/schemas.ts — TaxSchema

---

HIGH Not checking the error tuple before reading data

Wrong:

const [, link] = await wompi.paymentLinks.createPaymentLink(input);
return { linkId: link.id }; // TypeError if validation failed or key missing

Correct:

const [error, link] = await wompi.paymentLinks.createPaymentLink(input);
if (error) {
  return { error: error.message };
}
return { linkId: link.id };

Source: packages/core/src/schemas.ts

See also

• wompi-client-setup/SKILL.md — key types and error-tuple pattern