Widget & Web Checkout
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 de pagos. 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 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
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
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 transacion 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 isCOP
(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 modifiedredirect-url
(redirection URL): This is the URL to which the user will be redirected after competing a payment process, contained in the respective transactionid
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 deliveryaddress-line-2
: For extra referencescountry
: (Required) The ISO code of the country where the address is located (example: CO)city
: (Required) The city where the address is locatedphone-number
: (Required) The recipient's phone numberregion
: (Required) The region where the address is locatedname
: The name of the recipientpostal-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 emailfull-name
: The full name of the payerphone-number
: The payer's phone number, must be accompanied by thephone-number-prefix
fieldphone-number-prefix
: The prefix or country code of the payer's phone (example: +57), must be accompanied by thephone-number
fieldlegal-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 thelegal-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 thelegal-id
field.The types of document allowed are:CC
: Identity cardCE
: Immigration cardNIT
: Tax Identification NumberPP
: PassportTI
: Identity CardDNI
: National Identity DocumentRG
: Carteira de Identidade / Registro GeralOTHER
: 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 oflegal_id
andlegal_id_type
ofcustomer_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:
prod_integrity_Z5mMke9x0k8gpErbDqwrJXMqsI6SFli6
After you got our signature secret, you should generate a SHA256 hash with the followed data (the order matters):
- Transaction references: sk8-438k4-xmxm392-sn2m
- Transaction amount in cents: 2490000
- Transaction currency: COP
- 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:
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:
- Include the parameter
data-render="button"
, that indicates that you want to generate an automatic payment button. - 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
) - For the
shipping-address
,customer-data
andtax-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
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)
})