Cartões
A integração de pagamentos com cartão de crédito e/ou débito no Checkout API pode ser realizada de duas maneiras para websites. A integração recomendada é através do Card Payment Brick, onde o Brick se encarrega de buscar as informações necessárias para efetuar o pagamento. Mas, se você quiser ser o responsável por definir como essas informações serão buscadas, você pode realizar sua integração através de Core Methods.
Na integração via Card Payment para websites, a biblioteca MercadoPago.js, incluída no seu projeto durante a configuração do ambiente de desenvolvimento, é responsável por obter as informações necessárias para a geração de um pagamento. Ou seja, ela realiza uma busca pelos tipos de documentos disponíveis para o país correspondente e, conforme os dados do cartão são inseridos, também busca as informações relativas ao emissor e às parcelas disponíveis.
Toda a informação envolvida no processamento da transação é armazenada no backend, em conformidade com os padrões de segurança PCI.
Além disso, o componente oferece a possibilidade de orientar o usuário com alertas sobre campos incompletos ou possíveis erros ao preencher os dados, otimizando o processo de compra.
sequenceDiagram
participant Navegador as Navegador do comprador
participant _Frontend_ as _Frontend_ do integrador
participant MPjs as MercadoPago.js
participant _Backend_ as _Backend_ do integrador
participant API as API Mercado Pago
Navegador->>_Frontend_: 1. O comprador acessa a tela de pagamento.
_Frontend_->>MPjs: 2. O front-end do integrador baixa e inicializa o SDK JS do Mercado Pago.
_Frontend_->>Navegador: 3. O front-end do integrador exibe o formulário de pagamento.
Navegador->>_Frontend_: 4. O comprador preenche o formulário e finaliza o pagamento.
_Frontend_->>MPjs: 5. O front-end do integrador usa o SDK JS para criar o _token_ que conterá os dados do cartão de forma segura.
_Frontend_->>_Backend_: 6.O front-end do integrador envia o _token_ do cartão e os dados de pagamento para seu _backend_.
_Backend_->>API: 7. Do _backend_, são chamados os serviços do Mercado Pago para criar o pagamento.
API->>Navegador: 8. O front-end do integrador exibe ao comprador o resultado da operação.
API->>_Backend_: 9. O Mercado Pago pode enviar notificações via Webhook com atualizações do _status_ do pagamento.
_Backend_->>Navegador: 10. Se aplicável, o comprador é notificado sobre a atualização do pagamento.
Para avançar com a configuração de pagamentos com cartão de débito e/ou crédito via Card Payment, siga os passos abaixo.
processing_mode. Para mais informações, acesse a seção Modelo de integração.Para poder receber pagamentos, é necessário que você adicione no frontend um formulário que permita capturar os dados do pagador de maneira segura e possibilite a criptografia do cartão.
Essa inclusão deve ser feita por meio do Card Payment, que oferece um formulário otimizado com temas variados e inclui os campos necessários para pagamentos com cartões.
Para adicionar o Card Payment, primeiro realize sua configuração e inicialização a partir do frontend, como mostram os exemplos a seguir.
const renderCardPaymentBrick = async (bricksBuilder) => {
const settings = {
initialization: {
amount: 100.99, // valor total a ser pago
},
callbacks: {
onReady: () => {
/*
Callback chamado quando o Brick estiver pronto.
Aqui podem ser ocultos loadings do site, por exemplo.
*/
},
onSubmit: (formData, additionalData) => {
// callback chamado ao clicar no botão de envio de dados
return new Promise((resolve, reject) => {
const submitData = {
type: "online",
total_amount: String(formData.transaction_amount), // deve ser uma string com formato 00.00
external_reference: "ext_ref_1234", // identificador da origem da transação.
processing_mode: "automatic",
transactions: {
payments: [
{
amount: String(formData.transaction_amount), // deve ser uma string com formato 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) => {
// receber o resultado do pagamento
resolve();
})
.catch((error) => {
// lidar com a resposta de erro ao tentar criar o pagamento
reject();
});
});
},
onError: (error) => {
// callback chamado para todos os casos de erro do Brick
console.error(error);
},
},
};
window.cardPaymentBrickController = await bricksBuilder.create(
"cardPayment",
"cardPaymentBrick_container",
settings
);
};
renderCardPaymentBrick(bricksBuilder);O callback onSubmit do Brick obterá os dados mínimos necessários para a criação de um pagamento. Uma das informações retornadas é o CardToken, que representa de forma segura os dados do cartão. Esse token pode ser usado somente uma vez e expira dentro de 7 dias.
Além das informações mínimas, recomendamos incluir detalhes adicionais ou que possam facilitar o reconhecimento da compra por parte do comprador, aumentando assim a taxa de aprovação dos pagamentos. Consulte nossa Referência de APIAPI para conhecer em detalhe todos os parâmetros a serem enviados ao criar um pagamento, incluindo aqueles que podem melhorar sua taxa de aprovação, e verifique quais você deseja incluir nesta etapa.
Em seguida, adicione os campos relevantes ao objeto enviado, que são retornados na resposta do callback.
window.cardPaymentBrickController.unmount(). Ao entrar novamente, uma nova instância deve ser gerada.
Por fim, realize a renderização do Brick utilizando um dos exemplos abaixo<div id="cardPaymentBrick_container"></div> // O id deve corresponder ao valor enviado no método create() na etapa anteriorComo resultado, a renderização do Brick ficará semelhante à imagem abaixo.
Para avançar para a etapa de envio do pagamento, será necessário que seu backend possa receber as informações do formulário criado, junto com o token resultante da criptografia do cartão. Para isso, recomendamos disponibilizar um endpoint /Process_order que receba os dados coletados pelo Brick após a ação de submit.
O envio do pagamento deve ser realizado mediante a criação de uma order que contenha a transação de pagamento associada.
Para isso, envie uma requisição com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os parâmetros requeridos listados abaixo ao endpoint /v1/ordersPOST.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/orders'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "type": "online", "processing_mode": "automatic", "total_amount": "50.00", "external_reference": "ext_ref_1234", "payer": { "email": "test@testuser.com" }, "transactions": { "payments": [ { "amount": "50.00", "payment_method": { "id": "master", "type": "credit_card", "token": "1223123", "installments": 1 } } ] } }'
429 Too Many Requests, aguarde o tempo indicado no header Retry-After da resposta antes de tentar novamente. Consulte Possíveis erros para mais detalhes.Veja na tabela abaixo as descrições dos parâmetros que possuem alguma particularidade importante de ser destacada.
| Parâmetro | Tipo | Descrição | Obrigatoriedade |
Authorization | Header | Faz referência à sua chave privada, o Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`.. | Obrigatório |
X-Idempotency-Key | Header | Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no header da requisição, como um UUID V4 ou uma string aleatória. | Obrigatório |
processing_mode | Body. String | Modo de processamento da order. Os valores possíveis são: - automatic: para criar e processar a ordem em modo automático. - manual: para criar a order e processá-la posteriormente. Para mais informações, acesse a seção Modelo de integração. | Obrigatório |
total_amount | Body. String | Valor total da transação. | Obrigatório |
transaction.payments.payment_method.id | Body. String | Identificador do meio de pagamento. Neste caso, é a bandeira de cada cartão. Você pode consultar a lista completa de identificadores disponíveis enviando uma requisição ao endpoint Obter meios de pagamentoGET. | Obrigatório |
transaction.payments.payment_method.type | Body. String | Tipo de meio de pagamento. Para pagamentos com cartão de crédito, deve ser credit_card, e para pagamentos com cartão de débito, deve ser debit_card. | Obrigatório |
transaction.payments.payment_method.token | Body. String | Token do cartão. Campo obrigatório para pagamentos com cartão de crédito e débito. | Obrigatório |
Em caso de sucesso, a resposta será semelhante ao exemplo abaixo.
json{ "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "50.00", "total_paid_amount": "50.00", "country_code": "BRA", "user_id": "2021490138", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic_async", "created_date": "2025-04-17T21:41:33.96Z", "last_updated_date": "2025-04-17T21:41:35.144Z", "integration_data": { "application_id": "874202490252970" }, "transactions": { "payments": [ { "id": "PAY01JS2V6CM8KJ0EC4H504R7YE34", "amount": "50.00", "paid_amount": "50.00", "reference_id": "0002yjis6j", "status": "processed", "status_detail": "accredited", "payment_method": { "id": "elo", "type": "credit_card", "token": "519ada5ac7431ef6ce24ac19c38f6768", "installments": 1 } } ] } }
Dentre os parâmetros retornados, temos os indicados na tabela abaixo.
| Parâmetro | Tipo | Descrição |
transactions.payments.status | String | Status da transação. Por exemplo, processed indica que o pagamento foi aprovado. Consulte a seção Status da transação para ver todos os valores possíveis. |
transactions.payments.status_detail | String | Detalhe do status da transação. Por exemplo, accredited indica que o pagamento foi aprovado e creditado. |
transactions.payments.paid_amount | String | Valor efetivamente pago na transação. |