MercadoPago Custom Checkout

Official Content

Checkout steps

  • Previous Steps
    • Setting Credentials
    • Getting Payment Methods and Identification Types
  • Payment Procedure
    • Search for Customer
      • Create Customer if it does not already exist
    • Create card token
    • Create Payment
      • If success, associate card with user in MercadoPago


When using custom checkout, the user never leaves the seller’s site. 

Settting Credentials

First of all, you need to get your public key and access token from MercadoPago’s site.

This token is NOT the same as the one used in standard checkout, it does not have to be refreshed unless you explicitly decide to. 

Both keys can be obtained from your credentials page, on the custom checkout tab. (See Get MercadoPago Credentials)  


For testing, use sandbox ones. When going to production1, change it for production ones (you need MercadoPago’s homologation for production keys).

Modify the GetCurrentToken() procedure in order the return the corresponding Access Token, for instance: 

&Access_token = !"APP_USR-6971886488541892-011709-b9a53d06f2bd31277ac1c3b7e9cf23e7__LB_LA__-304915036"

1More information about production environment can be found here:

Note: you can manually refresh the keys from your credentials website. In case you do, you must update them in your GeneXus application.

Getting started with the Web Panel

First, you need to get the available payment methods and identification types (both vary depending on the seller’s country).
Payment Methods refer to credit cards, debit cards, MercadoPago credit, cash, etc.
Identification types refer to which method of identification is going to be used for the user (varies according to the country)

Getting payment methods and identification types


where the variable’s type is PaymentMethodsSDT. The procedure will return the information loaded into that variable.

You can now load the payment methods to a combo box

for &p in  &PaymentMethodsSdt 

&p is PaymentMethodsSDT.PaymentMethodsSDTItem type
&MetPago is VarChar(100), type combobox.

The same applies to identification types:

for &t in &TypesIdentificationSDT

&TypesIdentificationSDT: TypesIdentificationSDT
&t = TypesIdentificationSDT.TypesIdentificationSDTItem
&type = Character(20)
Note: Some countries (Ex: Mexico) don’t have identification types.

When using Credit Card, you must include a WebComponent (found on the SDK, named "WCCreditCardPayment"), which contains the necessary fields to create a credit card token (name, credit card number, security code, expiration month, expiration year).

Note: You must not change the variables' name in this WebComponent.

Payment Procedure

If Credit Card payment method is used, Credit Card information cannot go through a server without PCI certification, so a Javascript file is used to send this data directly to MercadoPago's servers.
To interact with this file, an External Object is used: "MercadoPagoJS".

Note: The Javascript file is extracted automatically by GeneXus. To use it in another KB, you must export it to a .XPZ and import it in your KB.

To be able to use this Javascript file, you must include it in your WebPanel, as well as MercadoPago's javascript API:


First, you need to create a credit card token (which will be used later to finish the payment). To generate this token, you just need to use the Javascript file, sending your public key as a parameter. 

Event 'Pay'

Important Note: It is imperative that you only call this Javascript in your "Pay" event, and no other instruction is programmed in that event. If not, credit card information will travel to your server without PCI Certification.

You must program three events, which are called depending on the Javascript's response:

Event MercadoPagoJS.FormatError(&ErrorMessage)

Event MercadoPagoJS.TokenFail(&TokenError)
    Msg("Payment Fail - " + &TokenError)

Event MercadoPagoJS.TokenReady(&CCToken)
    //Payment Procedure

FormatError is returned when one or more required fields are empty. &ErrorMessage contains a description of the problem. 

TokenFail is returned when a problem occurs on MercadoPago's API, (ex: wrong credit card number). &TokenError also contains information about the problem

TokenReady is returned when the token was generated correctly. &CCToken is the token's id, used later in the payment preference.

The rest of the payment's procedure must be programmed inside TokenReady event, as it is only executed when a valid credit card token is available.

Search for Customer

You must search for the user (in MercadoPago) using the SearchUser procedure where &Email is the user’s you want to search for e-mail.:


//If &ErrorCode = 0 you load the user
if & 
    for &s in &SearchUserSDT.results                                                          
        &user.UserId = &
        &user.UserMPId = &                                                              
        &user.UserEmail = &
        &user.UserForTest = false
        &user.UserType = UserType.Buyer

&SearchUserSDT is a SearchUserSDT variable.

Note: &user is a User type variable (transaction in which users are stored in your DataBase).
Note: User is an example transaction, each developer may create the user with the attributes it prefers.

Create Customer

//If &ErrorCode is not 0 (this means the user was not found), then you have to create a user (in MercadoPago):
MercadoPago.Users.CreateCustomer(&Email, &ClientSDT,&Message,&ErrorCode)
if &ErrorCode = 0
    &user = new()
    &user.UserId = &
    &user.UserMPId = &
    &user.UserNickName = &ClientSDT.nickname.Trim()
    &user.UserPassword = &ClientSDT.password.Trim()              
    &user.UserEmail = &
    &user.UserForTest = false
    &user.UserType = UserType.Buyer

Create Payment

Now you have to create the payment

&PaymentSDT = new()                                
&PaymentSDT.token = &CCToken

&CCToken is the card token returned by the Javascript File in the event TokenReady.
Complete the information about the payment:
-Transaction amount

Add items to the payment

&Item type: CreatePaymentSDT.additional_info.itemsItem
&Item = new()

To create the payment, there is a procedure


Associate Card with User

If &ErrorCode = 0 

ErrorCode = 0 means the payment was successful, you can then, associate the buyer to their credit card (in MercadoPago).

When payment is successful, you can add a security check, to test if credit card information went through the server or not.


This global event is executed in the Web Component included before.


Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.