Transactions

Create, fetch, list and void transactions. The core of the Wompi payments surface.

The transactions resource handles the actual money movement. There are four methods — createTransaction, getTransaction, listTransactions and voidTransaction — with different authentication requirements depending on what you’re doing.

Authentication matrix

createTransaction(input)

Create a new transaction. You must include at least one of payment_method or payment_source_id — the SDK validates the constraint locally before sending. Send both to charge a stored card source, which needs payment_method.installments.

const [merchantError, merchant] = await wompi.merchants.getMerchant();
if (merchantError) throw merchantError;

const acceptanceToken = merchant.presigned_acceptance?.acceptance_token;
const personalAuthToken =
  merchant.presigned_personal_data_auth?.acceptance_token;
if (!acceptanceToken || !personalAuthToken)
  throw new Error("Merchant has no acceptance tokens");

const [error, response] = await wompi.transactions.createTransaction({
  acceptance_token: acceptanceToken,
  accept_personal_auth: personalAuthToken,
  amount_in_cents: 2_490_000,
  currency: "COP",
  signature,
  customer_email: "buyer@example.com",
  reference: `order-${Date.now()}`,
  payment_method: { type: "CARD", token: cardToken, installments: 1 },
});

Input fields

Any other field Wompi documents also reaches the API — the SDK does not strip unknown keys from this payload.

Create with a stored payment source

// Re-charge a stored payment source — no card token, no signature handshake.
// `acceptanceToken` / `personalAuthToken` come from the merchant, as above.
const [error, response] = await wompi.transactions.createTransaction({
  acceptance_token: acceptanceToken,
  accept_personal_auth: personalAuthToken,
  amount_in_cents: 1_990_000,
  currency: "COP",
  signature,
  customer_email: "buyer@example.com",
  reference: `recur-${Date.now()}`,
  payment_source_id: 12_345, // requires the private key
  payment_method: { installments: 1 }, // required for a stored CARD source
});

getTransaction(id)

Look a transaction up by id. Useful for polling a PENDING status from a webhook handler or a status page.

const [error, response] = await wompi.transactions.getTransaction("txn_abc123");
if (error) {
  if ("type" in error && error.type === "NOT_FOUND_ERROR") return notFound();
  throw error;
}

response.status; // "PENDING" | "APPROVED" | "DECLINED" | "ERROR" | "VOIDED"

listTransactions(params)

Filtered list across all your merchant transactions. Requires the private key.

const [error, response] = await wompi.transactions.listTransactions({
  from_date: "2026-01-01",
  until_date: "2026-01-31",
  status: "APPROVED",
  page: 1,
  page_size: 50,
  order_by: "created_at",
  order: "DESC",
});
if (error) throw error;

response; // Transaction[] — the array directly; page through it with page/page_size

List parameters

• reference — exact match.
• from_date / until_date — YYYY-MM-DD.
• page (1 – 1 000 000), page_size (1 – 200).
• id, payment_method_type, status, customer_email.
• order_by (string), order ("ASC" / "DESC").

voidTransaction(id, input?)

Void or partially refund an approved CARD transaction. Without input the API voids the full amount; pass { amount_in_cents } for a partial refund.

// Full void.
const [error, response] =
  await wompi.transactions.voidTransaction("txn_abc123");

// Partial void / refund.
const [error, response] = await wompi.transactions.voidTransaction(
  "txn_abc123",
  {
    amount_in_cents: 1_000_000,
  },
);

// Wompi may answer with an empty 201 — response is undefined in that case.
response?.transaction?.status; // optional