Widget & Checkout Web

Accept payments on your website in minutes using one of our two Checkout options:

Widget	Web Checkout
Allow your customers to complete a payment without leaving your website, by simply including a <script> tag within our widget for payments (you got to be able to include Javascript in your site). You can see an example below	Let your customers complete a payment outside of your website, by using or Checkout using a standard HTML form.

Both integration methods offer a fast and safe payments experience for your customers.

Step by step

• Step 1 — Have your public business key.
• Step 2 — Generate a unique payment reference.
• Step 3 — Generate an integrity signature.
• Step 4 — Prepare the redirection URL where the user will go to after paying.
• Step 5 — Take into account the required and optional parameters for a transaction.
• Step 6 — Choose an integration method.
• Step 7 — Listen to a transaction's event using a webhook.

Use HTTPS

We strongly recommend using HTTPS on your website, since it will make your website feel safer for your customers and you will avoing being marked as an insecure site by Google, a change Google Chrome announced that will be implemented starting July 24, 2018. Which is important to keep in mind knowing that Google accounts more than 60% of web traffic.

Step 1: Prepare your public commerce key

For any Wompi integration you need to have a public business key that looks like the following:

pub_prod_Kw4aC0rZVgLZQn209NbEKPuXLzBD28Zx

Get your Wompi keys

To obtain your Wompi keys, please register on our Commerce Dashboard if you haven't yet. It's that easy!

This allows us to identify your account each time a payment is processed through Wompi. Click here to understand how commerce public and private keys work.

Remember that there are keys for both, production and sandbox environments

The sandbox keys (test environment) have the prefix pub_test_, while the production keys have the prefix pub_prod_. Real transactions use the production keys and for test transactions, while you are integrating and testing the service, use the sandbox keys.

Step 2: Generate a unique payment reference

For each purchase that your customers do on your website, you should generate a unique payment reference. This way it will be possible to identify and track each transaction that is completed on Wompi and it will also avoid accidental duplicate transactions. This means that once a reference is used for a payment on your account, it will not be possible to use it again.

We recommend using numeric or alphanumeric references, that can or cannot include dashes (-) or underscores (_). The following are valid reference examples:

• 3b4393bafed398ba2
• 54937
• 10384200283
• 58e281-177ab976cbf9-d162d2
• 38932_3293298
• 0f760951ed_a0086f

Step 3: Generate an integrity signature

To validate the integrity of the information of the transaction and avoid alterations, Wompi uses an asymmetric cryptographic hash.

We need the integrity secret, located on "Developers > Secrets for technical integration" section on your dashboard, in order to generate our integrity signature, it looks like:

It's important to make clear that this integrity secret is not the private or public key.

  prod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6

After you got our signature secret, you should generate a SHA256 hash with the followed data (the order matters):

1. Transaction references: sk8-438k4-xmxm392-sn2m
2. Transaction amount in cents: 2490000
3. Transaction currency: COP
4. Signatures integrity: prod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6

We should concat those values:

  "<Reference><Amount><Currency><IntegritySecret>"

With example values, we got:

  "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"

Important, when using the expiration-time parameter, it must be concatenated as an additional value:

1. Expiration date: 2023-06-09T20:28:50.000Z

The above values are concatenated with the additional value in the following order:

  "<Reference><Amount><Currency><ExpirationDate><IntegritySecret>"

This is how they would look with the additional example value:

  "sk8-438k4-xmxm392-sn2m2490000COP2023-06-09T20:28:50.000Zprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"

Into a SHA256 hash:

We recommend you to make this cryptography hash on the server side instead of frontend side, because you could expose the integrity secret to a potential hacker.

Ruby:

    # How to use it
    Digest::SHA2.hexdigest($concatenated_text)
    # Example
    Digest::SHA2.hexdigest("sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6") #"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

Php:

  // How to use it
  hash ("sha256", $concatenated_text);
  // Example
  hash ("sha256", "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"); //"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

Javascript:

  var concatenatedText = "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"
  // Example
  const encondedText = new TextEncoder().encode(concatenatedText);
  const hashBuffer = await crypto.subtle.digest('SHA-256', encondedText);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); // "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

Python:

  import hashlib
  # Example
  concatenated_text = "sk8-438k4-xmxm392-sn2m2490000COPprod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6"
  m = hashlib.sha256()
  m.update(bytes(cadena_concatenada))
  m.digest()
  #"37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"

We have to send this value into signature:integrity key:

<form>
  <script
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    ...
    >
  </script>
</form>

Step 4: Redirection URL

After finalizing a transaction, if desired, Wompi will redirect the user to a URL (which has to belong to your website), there he can see the end result (status) of the transaction. This can be done using the id of the transaccion, which will be available as a URL parameter.

For example, if your URL is:

https://mystore.com.co/payments/result

The URL Wompi will redirect the user will be similar to the following:

https://mystore.com.co/payments/result?id=01-1531231271-19365

That way you can use the parameter id available on the URL to verify the transaction using our API pointing to https://production.wompi.co/v1/transactions/<TRANSACTION_ID>. For instance: https://production.wompi.co/v1/transactions/01-1531231271-19365

Step 5: Transaction parameters

You can provide parameters for each transaction like the amount to be charged, the currency in which you want to charge, etc. Some of these parameters are a requirement while others are optional.

Required parameters

The following are the required parameters for creating a transaction:

• public-key (Public commerce key): Public commerce key.
• currency (Currency): Currency in which you will charge. The only currency currently available is COP (colombian pesos).
• amount-in-cents (Amount in cents): Amount to be charged in cents. For example, if you wish to charge $95.000 COP, you will enter: 9500000.
• reference (Unique payment reference): Unique payment reference.
• signature:integrity (Integrity signature): This is a cryptographic hash we use to verify that important values have not been modified.

Optional parameters

The following optional parameters, even though not necessary, provide a better integration experience:

• redirect-url (redirection URL): This is the URL to which the user will be redirected after completing a payment process, containing the respective transaction id.
• shipping-address (Shipping information): It is the customer's shipping address information, where you will receive the products and / or services, if needed. The data that can be requested are the following:
  • address-line-1: (Required) The address of the place of delivery.
  • address-line-2: For extra references.
  • country: (Required) The ISO 3166-1 Alpha-2 code (2 capital letters) of the country where the address is located (example: CO).
  • city: (Required) The city where the address is located.
  • phone-number: (Required) The recipient's phone number.
  • region: (Required) The region where the address is located.
  • name: The name of the recipient.
  • postal-code: The postal code of the recipient.
• collect-shipping (Activate shipping form): This parameter activates the shipping information view, and if the shipping address fields were filled in, they will appear pre-filled in the view.
• customer-data (Payer information): It is the payer's information, which will be pre-filled in the "Insert your contact information" view. The allowed data is:
  • email: The payer's email.
  • full-name: The full name of the payer.
  • phone-number: The payer's phone number, must be accompanied by the phone-number-prefix field.
  • phone-number-prefix: The prefix or country code of the payer's phone (example: +57), must be accompanied by the phone-number field.
  • legal-id: The payer's identity document number, this parameter activates the payer's identity document field in the "Insert your contact information" view and must be accompanied by the legal-id-type field.
  • legal-id-type: The payer's document type, this parameter activates the payer's identity document field in the "Insert your contact information" view and must be accompanied by the legal-id field. The types of document allowed are:
    • CC: Identity card.
    • CE: Immigration card.
    • NIT: Tax Identification Number.
    • PP: Passport,
    • TI: Identity Card.
    • DNI: National Identity Document.
    • RG: Carteira de Identidade / Registro Geral.
    • OTHER: Other.
• collect-customer-legal-id: Activates the payer's identity document field, using true as its value. This parameter activates the payer's identity document field in the "Insert your contact information" view. If the fields of legal_id and legal_id_type of customer_data where filled out, it will be pre-filled with the information.
• tax-in-cents (Detail of taxes in payment): It is the tax information in which you can detail the type of tax and the amount of the tax within the total price of the transaction in cents. The way to use it in the different forms of integration is explained later on. The types of taxes allowed are the following:
  • VAT: VAT (Value Added Tax).
  • CONSUMPTION: Consumption Tax.
• expiration-time: Date and time in ISO8601 format (UTC+0000), activates a countdown timer indicating the time remaining until the expiration of the payment start date.
• payment-method
  • reference-one: Optional field. Defaults to the IP address of the originating request. If reference-two and reference-three are sent without this field, the origin IP address will be assigned automatically. The definition of this value may vary depending on the merchant's economic activity, as specified in the official PSE documentation.
  • reference-two: Product opening date in format yyyymmdd
  • reference-three: Document number of the beneficiary of the financial product.

Please note: In order to mitigate fraud in the PSE service, additional actions have been defined that must be implemented by all companies linked to the Financial Services category. Among these actions is the inclusion of three mandatory fields in the transactional frame, related to the IP address of the user, the date the product was opened and the identification of the beneficiary.

If the above description is met, it is recommended to send the payment-method object with the reference-one, reference-two, reference-three and reference-three fields.

Optional encryption of reference fields (JWE)

If your business handles sensitive information in the reference-one, reference-two, or reference-three fields, you can encrypt them using JWE (JSON Web Encryption) before sending them. Wompi automatically detects whether a field is encrypted or in plain text. See the JWE encryption guide for PSE for details.

Taxes will not be added to the transaction amount. It is important to know that taxes sent in the taxes object will not be added to the transaction total. For example, in a transaction whose total (amount_in_cents) is COP$119,000 and whose VAT is COP$19.000, the latter amount is already part of the total, implying that: the base without taxes ($100,000) + VAT ($19,000) = the total ($119,000). In other words, Wompi will not add $19,000 to the $119,000, but will simply share this tax information with the respective payment processor.

Step 6: Choose an integration method

Choose one of the following two integration options:

• Widget: Allows your customers to complete a payment within your website using our Widget.
• Web: Your customers complete the payment on our Web Checkout.

Widget Checkout

This is the most simple method to get your customers to complete a payment without leaving your website. With only a few HTML lines, a payment button will be shown automatically.

By clicking on the button, the client will continue the payment process within our widget, without leaving your website. If you want a personalized payment button, head over to the custom button section.

In the following, you will see an example of the button generated with the same code that you can see below:

<form>
  <script
    src="https://checkout.wompi.co/widget.js"
    data-render="button"
    data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
    data-currency="COP"
    data-amount-in-cents="4950000"
    data-reference="4XMPGKWWPKWQ"
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    >
  </script>
</form>

The code above has the minimum neccessary parameters to generate a payment button that allows your customers to pay on our widget. Just like that, to generate a button you only need to include a <script> with the transaction parameters within a <form> tag in your code.

You only need to take into account three things to generate the button:

1. Include the parameter data-render="button", that indicates that you want to generate a payment button automatically.
2. For the parameters listed above you have to use the data- prefix on each one of them (i.e. data-reference, data-currency, data-amount-in-cents, etc) and use dashes (-) instead of underscores (_) for the names of each parameter.
3. For the shipping-address, customer-data and tax-in-cents parameters you must use a colon (:) to specify the type of information you want.

An example with all the parameters looks like the following:

<form>
  <script
    src="https://checkout.wompi.co/widget.js"
    data-render="button"
    data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
    data-currency="COP"
    data-amount-in-cents="7890000"
    data-reference="37DNKF84S92N1S"
    data-signature:integrity="37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5"
    data-redirect-url="https://transaction-redirect.wompi.co/check"
    data-expiration-time="2023-06-09T20:28:50.000Z"
    data-tax-in-cents:consumption="590000"
    data-tax-in-cents:vat="1290000"
    data-customer-data:email="lola@perez.com"
    data-customer-data:full-name="Lola Perez"
    data-customer-data:phone-number="3019777777"
    data-customer-data:phone-number-prefix="+57"
    data-customer-data:legal-id="123456789"
    data-customer-data:legal-id-type="CC"
    data-shipping-address:address-line-1="Carrera 123 #4-5"
    data-shipping-address:address-line-2="apto 123"
    data-shipping-address:country="CO"
    data-shipping-address:city="Bogota"
    data-shipping-address:phone-number="3019988888"
    data-shipping-address:region="Cundinamarca"
    data-shipping-address:name="Pedro Perez"
    >
  </script>
</form>

Web Checkout

This is the fastest method for integrating Wompi on your website, using only a standard HTML form:

<form action="https://checkout.wompi.co/p/" method="GET">
  <!-- REQUIRED -->
  <input type="hidden" name="public-key" value="MERCHANT_PUBLIC_KEY" />
  <input type="hidden" name="currency" value="CURRENCY" />
  <input type="hidden" name="amount-in-cents" value="AMOUNT_IN_CENTS" />
  <input type="hidden" name="reference" value="UNIQUE_PAYMENT_REFERENCE" />
  <input type="hidden" name="signature:integrity" value="INTEGRITY_SIGNATURE" />
  <!-- OPTIONAL -->
  <input type="hidden" name="redirect-url" value="REDIRECT_URL" />
  <input type="hidden" name="expiration-time" value="EXPIRATION-TIME" />
  <input type="hidden" name="tax-in-cents:vat" value="VAT_IN_CENTS" />
  <input type="hidden" name="tax-in-cents:consumption" value="CONSUMPTION_IN_CENTS" />
  <input type="hidden" name="customer-data:email" value="PAYER'S_MAIL" />
  <input type="hidden" name="customer-data:full-name" value="PAYER'S_NAME" />
  <input type="hidden" name="customer-data:phone-number" value="PAYER'S_PHONE_NUMBER" />
  <input type="hidden" name="customer-data:legal-id" value="PAYER'S_LEGAL_ID" />
  <input type="hidden" name="customer-data:legal-id-type" value="PAYER'S_LEGAL_ID_TYPE" />
  <input type="hidden" name="shipping-address:address-line-1" value="SHIPPING_ADDRESS" />
  <input type="hidden" name="shipping-address:country" value="COUNTRY_OF_SHIPPING_ADDRESS" />
  <input type="hidden" name="shipping-address:phone-number" value="RECIPIENT'S_PHONE_NUMBER" />
  <input type="hidden" name="shipping-address:city" value="CITY_OF_SHIPPING_ADDRESS" />
  <input type="hidden" name="shipping-address:region" value="REGION_OF_SHIPPING_ADDRESS" />
  <button type="submit">Pay with Wompi</button>
</form>

This way you only need to make sure to fill out the required parameters and include this code wherever you need your customers to see the button to complete a payment. Once they click it, they will be taken to our Web Checkout where they will be able to quickly and securely complete the payment.

Step 7: Listen to a transaction's event

Always use the events to finalize your integration.

Once the Widget or the Web Checkout has been integrated to your website, what remains to be done is to listen to an Event in your server, to find out when a transaction has been completed. Do not use the redirection as a validation method of your transactions, only for informative purposes for your users.

Once a customer has finished their transaction, Wompi will inform you the transaction has reached a final status using an Event. To accomplish this, you must provide an Event's URL (webhook), where Wompi will send a JSON object with the transaction information. Click here and visit the Events guide where we explain in detail everything about this feature.

Custom button (optional)

If you want to offer a personalized integration for your customers, for example a button with your own style or to open the widget for a given user action, you simply need to follow the next steps:

Step 1: Include the script inside the widget

Add this tag preferably within the <head> of your HTML:

<script type="text/javascript" src="https://checkout.wompi.co/widget.js"></script>

Step 2: Setup the transaction data

Setup an instance of the Checkout with the configuration object. In the following you will find the fields for this with sample values. All are required except redirectUrl.

var checkout = new WidgetCheckout({
  currency: 'COP',
  amountInCents: 2490000,
  reference: 'AD002901221',
  publicKey: 'pub_fENJ3hdTJxdzs3hd35PxDBSMB4f85VrgiY3b6s1',
  redirectUrl: 'https://transaction-redirect.wompi.co/check' // Optional
  expirationTime: '2023-06-09T20:28:50.000Z', // Optional
  taxInCents: { // Optional
    vat: 1900,
    consumption: 800
  }
  customerData: { // Optional
    email:'lola@gmail.com',
    fullName: 'Lola Flores',
    phoneNumber: '3040777777',
    phoneNumberPrefix: '+57',
    legalId: '123456789',
    legalIdType: 'CC'
  }
  shippingAddress: { // Optional
    addressLine1: "Calle 123 #4-5",
    city: "Bogota",
    phoneNumber: '3019444444',
    region: "Cundinamarca",
    country: "CO"
  }
})

Step 3: Open the widget

Finally, when you want to open the widget that you previously setup, you only need to call the open function with a callback function as its parameter, which will give you the information of the transaction as soon as it's completed. For example:

checkout.open(function ( result ) {
  var transaction = result.transaction
  console.log('Transaction ID: ', transaction.id)
  console.log('Transaction object: ', transaction)
})