Skip to main content

Wompi JS library reference

Wompi wants you to build not only the best, but also the most secure payment experiences for your customers. For that matter, we're making available the Wompi JS library.

By integrating Wompi JS you benefit from the best anti-fraud protection, while still offering a custom user experience every time your customers initiate a Transaction or create a Payment Source, by using our API.

Use Wompi JS and protect against fraud

Step by step

  • Step 1 — Include the library in your site
  • Step 2 — Initialize the library and use a sessionId

Step 1: Include the library

Inside the <head> and </head> tags of your website, include the Wompi JS library:

<script src="https://cdn.wompi.co/libs/js/v1.js" data-public-key="PUBLIC_KEY"></script>

Replace PUBLIC_KEY for your merchant's public key. Get to know everything about Wompi Keys and Environments by clicking here.

Recommended use
At minimum, include Wompi JS in your the page where a Transaction or a Payment Source is created. Ideally, include Wompi JS in every page of your website, to obtain the best results regarding fraud prevention, by allowing Wompi to detect potentially fraudulent behaviors.

Step 2: Initialize the library

By including the library, you'll now have the global variable $wompi, which must be initialized in order to obtain a sessionId, as follows:

$wompi.initialize(function ( data, error ) {
if ( error === null ) {
var sessionId = data.sessionId
// `sessionId` is a string, for example: "1289_1696830983722-ab493d40c02e-278bab34-323va3"
}
})

Inside the resulting data you'll fin the sessionId variable, which must be used when creating Transacciones or Payment Sources, as explained below.

What is a sessionId?
It's a datum that identifies a customer's device and its activity during the purchase process in your site, that Wompi uses to protect your business against fraudulent users.

Creating Transactions

You must send the sessionId together with the rest of the fields of a Transaction when using the POST /transactions endpoint. For example:

{
// The `sessionId` obtained on the `initialize` function
"session_id": sessionId,

// Other transaction fields
"amount_in_cents": 2500000,
"currency": "COP",
"customer_email": "john.smith@example.com",
"reference": "2322er3234ed4",
// Etc...
}

Creating Payment Sources

IMPORTANTE: Be aware that, as opposed to transaction, Payment Sources must always be created from the backend and not from the frontend, since the merchant's private key is used. Therefore, even though you always obtain the sessionId in the frontend, it must first be sent to the backend in order to create a Payment Source.

You must send the sessionId together with the rest of the fields of a payment source when using the POST /payment_sources endpoint from the backend:

{
// The `sessionId` obtained on the `initialize` function
"session_id": sessionId,

// Other payment source fields
"type": "CARD",
"token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301",
"customer_email": "john.smith@example.com"
// Etc...
}