Cards - Integrate payment methods - Mercado Pago Developers
Cards
The integration of payments with credit and/or debit cards in Checkout API can be done in two ways. The recommended integration is through the Card Payment Brick, where the Brick takes care of retrieving the necessary information to process the payment. However, if you prefer to be responsible for determining how this information will be retrieved, you can perform your integration using Core Methods.
In the integration through the Card Payment Brick, the MercadoPago.js library, included in your project during the configuration of the development environment, is responsible for obtaining the information required for processing a payment. This means it searches for the types of documents available for the corresponding country, and as the card data is entered, it also retrieves information related to the issuer and the available installments.
All information involved in processing the transaction is stored in the backend, in compliance with PCI security standards.
In addition, the component provides the ability to guide the user with alerts for incomplete fields or possible errors when filling out the data, optimizing the purchasing process.
With this, the implementation of the flow is transparent for those who are performing the integration, as shown in the diagram below.
To proceed with the setup of debit and/or credit card payments via Card Payment Brick, follow the steps below.
Remember: before setting up the payment methods, choose the way you will process your transactions. The processing mode, whether manual or automatic, will be defined at the time of order creation, using the processing_mode parameter. For more information, visit the section Integration model.
To receive payments, you need to add a form in the frontend that allows for securely capturing the payer's information and enables card encryption.
This inclusion should be done through the Card Payment Brick, which offers an optimized form with various themes and includes the necessary fields for card payments.
To add the Card Payment Brick, first configure and initialize it from the frontend, as shown in the examples below.
constrenderCardPaymentBrick=async(bricksBuilder)=>{const settings ={initialization:{amount:100.99,// total amount to be paid},callbacks:{onReady:()=>{/*
Callback called when Brick is ready.
Here you can hide loadings from your site, for example.
*/},onSubmit:(formData, additionalData)=>{// callback called when clicking on the submit data buttonreturnnewPromise((resolve, reject)=>{const submitData ={type:"online",total_amount:String(formData.transaction_amount),// should be a string in the format 00.00external_reference:"ext_ref_1234",// identifier of the transaction sourceprocessing_mode:"automatic",transactions:{payments:[{amount:String(formData.transaction_amount),// should be a string in the format 00.00 payment_method:{id: formData.payment_method_id,type: additionalData.paymentTypeId,token: formData.token,installments: formData.installments,},},],},payer:{email: formData.payer.email,identification: formData.payer.identification,},};fetch("/process_order",{method:"POST",headers:{"Content-Type":"application/json",},body:JSON.stringify(submitData),}).then((response)=> response.json()).then((response)=>{// receive payment resultresolve();}).catch((error)=>{// handle error response when trying to create payment reject();});});},onError:(error)=>{// callback called for all Brick error cases
console.error(error);},},};
window.cardPaymentBrickController =await bricksBuilder.create("cardPayment","cardPaymentBrick_container",
settings
);};renderCardPaymentBrick(bricksBuilder);
The onSubmit callback of the Brick will obtain the minimum necessary data for creating a payment. Among those minimal data, there is the CardToken, that safely represents the card data. This token can only be used once, and will expire within 7 days.
In addition to the minimum data, we recommend collecting additional details or those that can facilitate the recognition of the purchase by the buyer, thus increasing the payment approval rate. Consult our API Reference for detailed information on all the parameters to be sent when creating a payment, including those that could improve your approval rate, and check which ones you want to include at this stage.
Then, add the relevant fields to the object being sent, which are returned in the callback response.
Whenever the user leaves the screen where some Brick is displayed, it is necessary to destroy the current instance with the command window.cardPaymentBrickController.unmount(). When entering again, a new instance must be generated.
Finally, render the Brick using one of the examples below.
<divid="cardPaymentBrick_container"></div> // The ID must match the value sent in the create() method in the previous step
As a result, the rendering of the Brick will look similar to the image below.
To move on to the payment submission stage, your backend must be able to receive the information from the created form, along with the token resulting from the card encryption. For this, we recommend providing an endpoint /Process_order that accommodates the data collected by the Brick after performing the submit action.
To configure the installments displayed on the frontend, see the Configure installments section of the Card Payment Brick. If you want to configure interest-free installments, please refer to the Support Center documentation.
The payment submission must be made by creating an order that contains associated payment transactions.
To do this, send a POST with your test Access TokenTesting private key of the application created in Mercado Pago, that is used in the backend. You can access it through Your integrations > Application details > Testing > Testing credentials. and the required parameters listed below to the endpoint /v1/ordersAPI and execute the request.
See the table below for descriptions of the parameters that have some important particularity that should be highlighted.
Atribute
Type
Description
Required/Optional
Authorization
Header
Refers to your private key, or Access Token. Use the test Access TokenTesting private key of the application created in Mercado Pago, that is used in the backend. You can access it through Your integrations > Application details > Testing > Testing credentials. in development environments, and the production Access TokenPrivate key of the application created in Mercado Pago, that is used in the backend when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials. for real payments.
Required
X-Idempotency-Key
Header
Idempotency key. It is used to ensure that each request is processed only once, avoiding duplications. Use a unique value in the header of your request, such as a UUID V4 or random strings.
Required
processing_mode
Body. String
Processing mode of the order. The possible values are:
- automatic: to create and process the order in automatic mode.
- manual: to create the order and process it later.
Payment method identifier. In this case, it is the brand of each card. You can check the complete list of available identifiers by sending a request to the Get payment methods endpoint.
Required
transaction.payments.payment_method.type
Body. String
Payment method type. For credit card payments, it should be credit_card, and for debit card payments, it should be debit_card.
Required
To learn in detail about all the parameters sent and returned in this request, please refer to our API Reference. Additionally, if you receive an error when submitting the payment, you can consult our list of errors.
In case of success, the response will look like the example below.
If you created the order manually, remember that processing the payment requires an additional step, which is the call to the Process order API. Additionally, this mode will allow you to reserve and capture funds. Refer to the Reserve, capture, and cancel funds section for more information.
Once the order and payment are created, you can check the possible statuses by going to the Order status and Transaction status sections, respectively.
