Widget & Web Checkout

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

WidgetWeb Checkout
Allow your customers to complete a payment without leaving your website, by simply including a <script> tag within our widget de pagos. You can see an example belowLet 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 merchant public key.
  • Step 2 — Generate a unique payment reference
  • Step 3 — Prepare the redirection URL where the user will go to after paying
  • Step 4 — Take into account the required and optional parameters for a transaction
  • Step 5 — Generate an integrity signature (optional)
  • 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 cuastomers and you will avoing being marked as an insecure site by Google.

Step 1: Prepare your public account key

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

pub_prod_Kw4aC0rZVgLZQn209NbEKPuXLzBD28Zx
Get your Wompi keys
To obtain your Wompi account keys, plese register on our Merchants Dashboard if you haven't yet. It's that easy!

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

Rembember that there are keys for both production and sabdbox environments

The sandbox keys (test environment) have the prefix pub_test_, while the production keys have the prefix pub_prod_. For real transactions usea 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: Redirection URL

After finalizing a transaction Wompi will redirect the user to a URL (which should belong to your website), on which he can see the end result (status) of the transaction, which will be available as a URL parameter.

For example, if your URL is:

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

The URL to which Wompi will redirect 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 4: Transaction parameters

You can provide parameters for each transaction like the amount to be charged and the currency in which you wan to charge for example. Some of these parameters are required while others are optional.

Required parameters

The following are the required parameters for creating a transaction:

  • public-key (Public account key): Public account 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 should enter: 9500000
  • reference (Unique payment reference): Unique payment reference.

Optional parameters

  • signature:integrity (Integrity signature): This is a cryptographic hash we use to verify that important values have not been modified
  • redirect-url (redirection URL): This is the URL to which the user will be redirected after competing a payment process, contained in 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. 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 code 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 "Ingresa tus datos" 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 "Ingresa tus datos" 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 "Ingresa tus datos" 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): This parameter activates the payer's identity document field in the "Ingresa tus datos" view, and if filled out the fields of legal_id andlegal_id_type of customer_data, 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. The types of taxes allowed are the following:
    • VAT: VAT (Value Added Tax)
    • CONSUMPTION: Consumption Tax

Step 5: Generate an integrity signature (optional)

We need the integrity secret, located on "My account > Secrets" section on you dashboard, in order to generate our integrity signature, it looks like:

The integrity secret is not the private key
It's important to make it clear 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"

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 should send this value into signature:integrity key:

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

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 the 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 showed 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.

Next 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. 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 two things to generate the button:

  1. Include the parameter data-render="button", that indicates that you want to generate an automatic payment button.
  2. For the parameters listed above you should use the data- prefix on each one, and to specify it (i.e. data-reference, data-currency, data-amount-in-cents)
  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-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" />
  <!-- OPTIONAL -->
  <input type="hidden" name="signature:integrity" value="INTEGRITY_SIGNATURE" />
  <input type="hidden" name="redirect-url" value="REDIRECT_URL" />
  <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

Once a customer has finished their payment flow regarding a 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.

Test transactions

This information was moved
Find all Sandbox transactions test data in:
Test Data for Sandbox.

Custom button (optional)

If you want to offer a personalized integration for your customers, for example a button with your own styles or 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 prefrerably within the <head> of your HTML:

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

Step 2: Test the transaction data

Setup an instance of the Checkout with the configuration object. Next we show 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
  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 the only parameter. For example:

checkout.open(function ( result ) {
  var transaction = result.transaction
  console.log('Transaction ID: ', transaction.id)
  console.log('Transaction object: ', transaction)
})
← Environments and KeysTest Data for Sandbox →