@pulgueta/wompi

API Reference

Payment sources

Turn a card or Nequi token into a long-lived payment source you can re-charge.

A payment source is Wompi's way of storing a tokenized card or Nequi account against a customer. Once created, you can re-charge it by passing its numeric id into createTransaction — no further tokenization or acceptance handshake needed.

createPaymentSource(input)

Promote a one-time token into a reusable source. You'll need a fresh acceptance token from merchants.getMerchant() — Wompi treats this as a separate customer consent.

ts 
// 1. Tokenize the card (or Nequi account) up-front.
const [tokenError, token] = await wompi.tokens.tokenizeCard({
  number: "4242424242424242",
  cvc: "123",
  exp_month: "12",
  exp_year: "29",
  card_holder: "PEDRO PEREZ",
});
if (tokenError) throw tokenError;

// 2. Fetch a fresh acceptance token from the merchant resource.
const [merchantError, merchant] = await wompi.merchants.getMerchant();
if (merchantError) throw merchantError;

// 3. Convert the card token into a long-lived payment source.
const [error, response] = await wompi.paymentSources.createPaymentSource({
  type: "CARD",
  token: token.id,
  acceptance_token: merchant.presigned_acceptance!.acceptance_token,
  customer_email: "buyer@example.com",
});
if (error) throw error;

response.id; // numeric id — store this against your user

Input

FieldTypeNotes
type"CARD" | "NEQUI"The token's source kind.
tokenstringOutput of tokens.tokenizeCard / tokenizeNequi.
acceptance_tokenstringFresh value from the merchant resource.
customer_emailemailThe customer this source belongs to.

getPaymentSource(id)

Look a payment source up by its numeric id.

ts 
const [error, response] = await wompi.paymentSources.getPaymentSource(12_345);
if (error) throw error;

response.id;
response.status; // "AVAILABLE" | "PENDING"
response.type;   // "CARD" | "NEQUI"

Response

FieldTypeNotes
idnumberStable, persist this against your user.
status"AVAILABLE" | "PENDING"PENDING for Nequi until the customer approves.
type"CARD" | "NEQUI" | undefinedSource kind.
tokenstring?The underlying token.
customer_emailstring?Owning customer.
public_dataobject?{ type, phone_number? } — safe to surface in the UI.

Charging a stored source

Drop the id into createTransaction as payment_source_id. Note the change in auth — using payment_source_id requires the private key, not the public one.

ts 
const [error, response] = await wompi.transactions.createTransaction({
  acceptance_token,
  amount_in_cents: 990_000,
  currency: "COP",
  signature,
  customer_email: "buyer@example.com",
  reference: `recur-${Date.now()}`,
  payment_source_id: 12_345, // ← reusing the stored source
});
Navigation