@pulgueta/wompi

Core Concepts

Integrity signature

What the Wompi integrity signature is, how getSignatureKey computes it, and the rules to follow.

Wompi requires every createTransaction call to include a signature field — an SHA-256 hex digest over the transaction's reference, amount, currency and (when applicable) expiration, salted with your merchant integrity key. This proves the request was built server-side and prevents tampering with the amount in transit.

Usage

Import getSignatureKey from the /server subpath. It uses Node's built-in Crypto API so it runs unchanged on Node, edge runtimes and modern serverless platforms.

lib/sign.ts 
import { getSignatureKey } from "@pulgueta/wompi/server";

const signature = await getSignatureKey({
  reference: "order-12345",
  amountInCents: 2_490_000,
  integrityKey: process.env.WOMPI_INTEGRITY_KEY!,
});

The formula

The hashed string is the concatenation of:

<reference><amountInCents><currency><expirationTime?><integrityKey>

// hashed as utf-8 with SHA-256, then expressed as lowercase hex.
  • reference — must match the same string you pass to createTransaction({ reference }).
  • amountInCents — the integer in cents, exactly as you'll send it. Never multiply by 100 here; the amount is already in cents.
  • currency — defaults to "COP". Only COP is currently accepted by Wompi, but the field is hashed so it has to match the body.
  • expirationTime — include it only if the transaction sets expiration_time. Omit otherwise; the hash uses an empty string in its place.
  • integrityKey — your merchant integrity secret. Read it from a server-only env var; never expose it to the browser.

With expiration_time

If the transaction carries an expiration_time, the signature must hash the same value, right before the integrity key.

ts 
// When the transaction sets expiration_time, hash the same value here.
const expirationTime = "2026-12-31T23:59:59Z";

const signature = await getSignatureKey({
  reference: "order-12345",
  amountInCents: 2_490_000,
  currency: "COP",
  expirationTime,
  integrityKey: process.env.WOMPI_INTEGRITY_KEY!,
});

const [error] = await wompi.transactions.createTransaction({
  // ... other fields
  signature,
  expiration_time: expirationTime,
});

Validation

getSignatureKey throws a WompiError if amountInCents is negative or not an integer. Every other field is passed through as-is.

Navigation