MercadoPago Custom Checkout

Official Content

Checkout steps

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

 

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

Setting 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 or basic 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)  

MPCustomCredentials_20181010131210_1_png

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 = !"TEST-6735657952668800-011909-......"

Modify the GetPublicKey() procedure with their corresponding Public Key:

&public_key = !"TEST-9e654de5-c129-......"

1More information about production environment can be found here:
https://www.mercadopago.com.ar/developers/en/guides/payments/api/goto-production/

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

Getting payment methods and identification types

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, ticket, cash, etc.
Identification types refer to which method of identification is going to be used for the user (varies according to the country)

You can get the available Payment Methods as follows:

MercadoPago.PaymentMethods.GetPaymentMethods(&PaymentMethodsSDT)

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 
    &MetPago.AddItem(&p.id,&p.name) 
Endfor

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

The same applies to Identification Types:

MercadoPago.Users.GetIdentificationTypes.Call(&TypesIdentificationSDT)
for &t in &TypesIdentificationSDT
    &type.AddItem(&t.id,&t.name)
Endfor

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

Paying with Credit or Debit Cards

When you opt for payment by credit or debit card, there are two important security-related considerations:

  1. To make the payment you must first obtain a Token from the card details.
  2. There is a method to obtain the token from the data on the card, but the card information cannot travel through servers other than PCI Compliant. In such cases, it should be sent directly to the server from the client-side. For security reasons, it is very important that these data never reach your servers

Create a Card Token

The GeneXus SDK has a different approach for creating the card token depending on whether you are performing the checkout process from a Web or Smart Device application.

Web Checkout

In your Web Panel for Checkout, you must include a WebComponent (found on the SDK, named "WCCreditCardPayment"), which contains the necessary protected fields to create a card token (name, credit card number, security code, expiration month, expiration year).

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

A Javascript file is used to send this data directly to MercadoPago's servers, as this information cannot go through a server without PCI certification. 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 Web Panel, as well as MercadoPago's javascript API:

Form.JScriptSrc.Add('https://secure.mlstatic.com/sdk/javascript/v1/mercadopago.js')
Form.JScriptSrc.Add('CreateCardToken.js')

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'
    &MercadoPagoJS.SendCardTokenHTML(&public_key)
EndEvent

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)
    Msg(&ErrorMessage)
EndEvent

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

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

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. 

Smart Device Checkout

In order to obtain the card token from a Smart Device Application, an External Object called MercadoPagoCheckout needs to be used. This external object allows you to send card information and get the corresponding token in a secure way, interacting directly with Mercado Pago's server. 

The MercadoPagoCheckout External Objets has to methods:

  • GetCardToken

Receives the type of card as a parameter (Visa, Master, etc. - this is a list of payment methods), card number, CVV, owner name and document (identification type), card expiration month and year. 

It returns an SDT containing the response of MercadoPago servers with the token generated for the card along with the last four digits of the card, or an error code in case of failure, defined in the MercadoPagoErrorCode domain:

 imagen_20191021125333_1_png

  • GetSavedCardToken

Receives the card_id of a previously saved card for the customer with their CVV and returns an SDT containing the response of MercadoPago servers with the token generated for the card along with the last four digits of the card, or an error code in case of failure, defined in the MercadoPagoErrorCode.

Warning: To use this method, you need to set the Public Key and Access Token Mercado Pagos's properties in the main Smart Device object.
 
To get these values, see Setting Credentials above.

Payment Procedure

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.:

MercadoPago.Users.SearchCustomer(&Email,&SearchUserSDT,&Message,&ErrorCode)

//If &ErrorCode = 0 you load the user
if &SearchUserSDT.paging.total=1 
    for &s in &SearchUserSDT.results                                                          
        &user.Load(&s.id.Trim())
        &user.UserId = &s.id.Trim()
        &user.UserMPId = &s.id.Trim()                                                              
        &user.UserEmail = &s.email.Trim()
        &user.UserForTest = false
        &user.UserType = UserType.Buyer
        &user.Save()     
        commit
    endfor
endif

&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 = &ClientSDT.id.Trim()
    &user.UserMPId = &ClientSDT.id.Trim()
    &user.UserNickName = &ClientSDT.nickname.Trim()
    &user.UserPassword = &ClientSDT.password.Trim()              
    &user.UserEmail = &ClientSDT.email.Trim()
    &user.UserForTest = false
    &user.UserType = UserType.Buyer
    &user.Save()                                    
    commit                                               
endif

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 (for Web checkout) or by means of the MercadoPagoCheckout external object (for SD checkout)
Complete the information about the payment:
-Installments
-Transaction amount
-Description
-Etc

Add items to the payment

&Item type: CreatePaymentSDT.additional_info.itemsItem
&Item = new()
//-Id
//-Title
//-Quantity
//-Unit_Price
&PaymentSDT.additional_info.Items.Add(&Item)

To create the payment, there is a procedure

MercadoPago.Payments.CreatePayment(&PaymentSDT,&PaymentInfoSDT,&Message,&ErrorCode)

Associate Card with User

If &ErrorCode = 0 
    MercadoPago.Payments.AddCard(&PaymentInfoSDT.payer.id,&CCToken,&Message,&ErrorCode)
EndIf

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 (for Web Checkout)

GlobalEvents.VariablesNotInServerSecurityCheck()

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