Salvar cartões
Armazene os dados do comprador para reutilizar dados de pagamento já tokenizadas pela API do Mercado Pago. Isso evita o reenvio de dados sensíveis em cada transação, reduz erros de preenchimento e simplifica o fluxo de autorização. Também permite reutilizar cartões previamente validados, diminuindo recusas por inconsistência de dados.
Veja abaixo as documentações para implementar e gerenciar cartões salvos na sua integração.
Crie o cliente e o cartão através das APIs de Criar clienteAPI e Salvar cartãoAPI. Para isso, utilize seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend para operações de produção. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Credenciais de produção..
Você pode realizar esta operação via API do Mercado Pago ou por meio dos nossos SDKs.
Primeiro, envie um POST ao endpoint /v1/customersAPI para criar o cliente.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer APP_USR-1*********685765-12*********1b4332e5c*********e077d7679*********664' \ -d '{ "email": "jhon@doe.com", "first_name": "Jhon", "last_name": "Doe", "phone": { "area_code": "55", "number": "991234567" }, "identification": { "type": "CPF", "number": "12345678900" }, "default_address": "Home", "address": { "id": "123123", "zip_code": "01234567", "street_name": "Rua Exemplo", "street_number": 123, "city": {} }, "date_registered": "2021-10-20T11:37:30.000-04:00", "description": "Description del user", "default_card": "None" }'
| Campo | Descrição | Obrigatoriedade |
email | Endereço de e-mail do cliente. Se você utilizar usuários de teste, o e-mail deve seguir o formato test_payer_[0-9]{1,10}@testuser.com. | Obrigatório |
first_name | Nome do cliente. | Opcional |
last_name | Sobrenome do cliente. | Opcional |
phone | Objeto que contém as informações de telefone do cliente. | Opcional |
phone.area_code | Código de área do telefone. | Opcional |
phone.number | Número de telefone sem código de área. | Opcional |
identification | Objeto que contém as informações de identificação do cliente. | Opcional |
identification.type | Tipo de documento de identidade (por exemplo: CPF, DNI, CNPJ). | Opcional |
identification.number | Número do documento de identidade. | Opcional |
default_address | Nome do endereço padrão do cliente. | Opcional |
address | Objeto que contém as informações de endereço do cliente. | Opcional |
address.id | Identificador do endereço. | Opcional |
address.zip_code | Código postal do endereço. | Opcional |
address.street_name | Nome da rua. | Opcional |
address.street_number | Número do endereço. | Opcional |
address.city | Objeto que contém as informações da cidade. | Opcional |
date_registered | Data de registro do cliente no formato ISO 8601. | Opcional |
description | Descrição adicional do cliente. | Opcional |
default_card | Identificador do cartão padrão. Pode ser "None" se não houver cartão padrão. | Opcional |
Em seguida, envie um POST ao endpoint /v1/customers/{id}/cardsAPI com o ID do Cliente (customer_id) no path para realizar a associação, e o token de cartão no body da requisição.
curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \ -d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
| Campo | Descrição | Obrigatoriedade |
token | Token criado (geralmente via SDKs) que representa os dados sensíveis do cartão de forma segura. | Obrigatório |
Após a criação bem-sucedida, os objetos serão identificados com estes prefixos:
| Prefixo | Descrição | Exemplo |
customer | Prefixo do cliente. | custID+xyz123 |
card | Prefixo do cartão. | card_abc456 |
A resposta trará o seguinte resultado:
json
{ "id": "123456789-jxOV430go9fx2e", "email": "test_payer_12345@testuser.com", ... "default_card": "1490022319978", "default_address": null, "cards": [{ "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001", ... }], "addresses": [], "live_mode": false }
invalid parameter com código HTTP 400, revise o parâmetro payment_method_id e certifique-se de que o valor tenha sido inserido corretamente. Além disso, ao utilizar usuários de teste, o e-mail do cliente deve seguir obrigatoriamente o formato test_payer_[0-9]{1,10}@testuser.com.Atualize qualquer informação de um cliente, como endereço, cartão ou e-mail. Você pode realizar esta operação via API do Mercado Pago ou por meio dos nossos SDKs.
Envie um PUT ao endpoint /v1/customers/{id}API com o ID do Cliente (customer_id) no path e os atributos a modificar no body da requisição.
customer_id, envie um GET ao endpoint /v1/customers/searchAPI para obter a informação. Além disso, o campo email só pode ser atualizado se o cliente ainda não tiver um endereço de e-mail associado.curl
curl -X PUT \ 'https://api.mercadopago.com/v1/customers/{id}' \ -H 'Authorization: Bearer ACCESS_TOKEN_ENV' \ -d '{ "email": "user@user.com", "first_name": "john", "last_name": "wagner", "address": { "zip_code": "52", "street_name": "Av. das Nações Unidas", "street_number": "2" }, "phone": { "area_code": "11", "number": "001234567" }, "identification": { "type": "CPF", "number": "12341234" }, "description": "Informações do cliente" }'
O endpoint aceita a modificação de todos os atributos descritos na tabela a seguir.
| Atributo | Descrição |
address | Endereço do cliente. |
default_address | ID do endereço padrão do cliente para envios. |
default_card | ID do cartão padrão do cliente para realizar pagamentos. |
description | Informações adicionais ou notas sobre o cliente. |
email | Endereço de e-mail do cliente. Só pode ser atualizado se o cliente ainda não tiver um endereço de e-mail associado em sua conta. |
first_name | Nome do cliente. |
last_name | Sobrenome do cliente. |
phone | Número de telefone do cliente. |
identification | Tipo e número de documento de identificação do cliente. |
A resposta trará o seguinte resultado:
json
{ "id": "xxxxxxxxxxxxxxxxxxxxx", "email": "user@user.com", "first_name": "john", "last_name": "wagner", "phone": { "area_code": "11", "number": "001234567" }, "identification": { "type": "CPF", "number": "12341234" }, "address": { "zip_code": "52", "street_name": "Av. das Nações Unidas", "street_number": 2 }, "description": "Informações do cliente", "date_created": "2021-05-25T15:36:23.541Z", "metadata": {}, "cards": [ {} ], "addresses": [ {} ] }
customer_id não for enviado, a resposta retornará o erro "message": "missing customer id".Obtenha dados específicos de um cliente, como ID, endereço ou data de registro, através da API de Clientes. Você pode realizar esta operação via API do Mercado Pago ou por meio dos nossos SDKs.
Envie um GET ao endpoint /v1/customers/searchAPI especificando o e-mail do cliente como parâmetro de consulta.
curl
curl -X GET \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/search?email=test_user_19653727@testuser.com'
A resposta mostrará este resultado:
json
{ "paging": { "limit": 10, "offset": 0, "total": 1 }, "results": [ { "address": { "id": null, "street_name": null, "street_number": null, "zip_code": null }, "addresses": [], "cards": [ { ... } ], "date_created": "2017-05-05T00:00:00.000-04:00", "date_last_updated": "2017-05-05T09:23:25.021-04:00", "date_registered": null, "default_address": null, "default_card": "1493990563105", "description": null, "email": "test_payer_12345@testuser.com", "first_name": null, "id": "123456789-jxOV430go9fx2e", "identification": { "number": null, "type": null }, "last_name": null, "live_mode": false, "metadata": {}, "phone": { "area_code": null, "number": null } } ] }
Associe cartões adicionais a um cliente registrado. Você pode realizar esta operação via API do Mercado Pago ou por meio dos nossos SDKs.
Envie um POST ao endpoint /v1/customers/{customer_id}/cardsAPI com o ID do Cliente (customer_id) no path e os dados do cartão no body da requisição.
customer_id) e o ID do Cartão (id). O último cartão salvo se converte automaticamente no DefaultCard.curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \ -d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
A resposta trará o seguinte resultado:
json
{ "id": "1493990563105", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "503175", "last_four_digits": "0604", "payment_method": { "id": "master", "name": "master", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/master.gif" }, "security_code": { "length": 3, "card_location": "back" }, "issuer": { "id": 3, "name": "Mastercard" }, "cardholder": { "name": "Card holdername", "identification": { "number": "12345678", "type": "DNI" } }, "date_created": "2017-05-05T09:22:30.893-04:00", "date_last_updated": "2017-05-05T09:22:30.893-04:00", "customer_id": "255276729-yLOTNHQjpDWw1X", "user_id": "255276729", "live_mode": false }
Consulte todos os cartões associados a um cliente. Você pode realizar esta operação via API do Mercado Pago ou por meio dos nossos SDKs.
Envie um GET ao endpoint /v1/customers/{customer_id}/cardsAPI com o ID do Cliente (customer_id) no path.
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
A resposta será um array com todos os objetos de cartão salvos para o cliente.
json
[{ "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001", ... }]
Para que um cliente realize um pagamento com cartões salvos, é necessário capturar novamente o código de segurança (CVV), pois o Mercado Pago não armazena esse dado por motivos de segurança. Essa operação pode ser realizada via API do Mercado Pago ou por meio dos nossos SDKs.
1. Mostrar lista de cartões salvos
Mostre ao comprador a lista de cartões salvos para que ele escolha a opção desejada.
Para isso, envie um GET ao endpoint /v1/customers/{customer_id}/cardsAPI com o ID do Cliente (customer_id) no path.
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
2. Criar formulário de pagamento
Depois de mostrar os cartões salvos ao comprador, prossiga com a criação do formulário de pagamento.
Esta etapa permite ao comprador ver onde deve incluir o código de segurança (CVV) do cartão selecionado. Para realizá-la, implemente o código a seguir diretamente no seu projeto.
html
<style> #form-checkout { display: flex; flex-direction: column; max-width: 600px; } .container { height: 18px; display: inline-block; border: 1px solid rgb(118, 118, 118); border-radius: 2px; padding: 1px 2px; } </style> <form id="form-checkout" method="POST" action="/process_payment"> <select type="text" id="form-checkout__cardId"></select> <div id="form-checkout__securityCode-container" class="container"></div> <input name="token" id="token" hidden> <button>Enviar</button> </form> <script> const mp = new MercadoPago('TEST-2bf9f710-6a6e-47c8-a207-79f5e73b464c'); const securityCodeElement = mp.fields.create('securityCode', { placeholder: "CVV" }).mount('form-checkout__securityCode-container'); const customerCards = [{ "id": "3502275482333", "last_four_digits": "9999", "payment_method": { "name": "amex", }, "security_code": { "length": 4, } }]; function appendCardToSelect() { const selectElement = document.getElementById('form-checkout__cardId'); const tmpFragment = document.createDocumentFragment(); customerCards.forEach(({ id, last_four_digits, payment_method }) => { const optionElement = document.createElement('option'); optionElement.setAttribute('value', id) optionElement.textContent = `${payment_method.name} ended in ${last_four_digits}` tmpFragment.appendChild(optionElement); }) selectElement.appendChild(tmpFragment) } appendCardToSelect(); </script>
3. Captura do código de segurança e criação do token
Após exibir os cartões salvos e criar o formulário de pagamento, o próximo passo é capturar o código de verificação (CVV) do cartão e gerar o token de segurança.
Para isso, você deve criar um token enviando o formulário com o ID do cartão selecionado pelo cliente e o código de segurança (CVV) utilizando o código Javascript a seguir.
javascript
const formElement = document.getElementById('form-checkout'); formElement.addEventListener('submit', e => createCardToken(e)); const createCardToken = async (event) => { try { const tokenElement = document.getElementById('token'); if (!tokenElement.value) { event.preventDefault(); const token = await mp.fields.createCardToken({ cardId: document.getElementById('form-checkout__cardId').value }); tokenElement.value = token.id; console.log(tokenElement); } } catch (e) { console.error('error creating card token: ', e) } }
4. Criar o pagamento
Uma vez que você tenha obtido o token de segurança do cartão na etapa anterior, o passo final é criar o pagamento com o valor correspondente.
Envie um POST ao endpoint /v1/paymentsAPI incluindo o payer.id e o token no corpo da solicitação, enviando os seguintes dados.
curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 100, "token": "ff8080814c11e237014c1ff593b57b4d", "installments": 1, "payer": { "type": "customer", "id": "123456789-jxOV430go9fx2e" } }'
| Campo | Descrição |
payer.id | ID do cliente ao qual pertence o cartão. |
token | Token recém-obtido que substitui os dados sensíveis do cartão e o CVV. |
transaction_amount | Valor da transação. |
Realiza a exclusão de um cartão específico associado a um cliente salvo, assegurando a atualização dos dados. A operação está disponível via API do Mercado Pago ou pelos SDKs disponíveis.
Envie um DELETE ao endpoint /v1/customers/{customer_id}/cards/{id}API com o ID do Cliente (customer_id) e o ID do Cartão (id) como parâmetros de path.
curl
curl -X DELETE \ 'https://api.mercadopago.com/v1/customers/12123adfasdf123u4u/cards/12123adfasdf123u4u'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer TEST-7434*********159-03141*********cee51edf8*********f94f589-1*********' \
A resposta trará este resultado:
json
{ "id": "8987269652", "expiration_month": 7, "expiration_year": 2023, "first_six_digits": "503143", "last_four_digits": "6351", "payment_method": { "id": "master", "name": "Mastercard", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/master.gif" }, "security_code": { "length": 3, "card_location": "back" }, "issuer": { "id": 24, "name": "Mastercard" }, "cardholder": { "name": "APRO", "identification": { "number": "01234567890", "type": "CPF" } }, "date_created": "2021-03-16T16:08:21.000-04:00", "date_last_updated": "2021-03-16T16:14:40.962-04:00", "customer_id": "470183340-cpunOI7UsIHlHr", "user_id": "470183340", "live_mode": true }
Crie um novo endereço para um cliente salvo através da API do Mercado Pago. Isso permite associar múltiplos endereços a um mesmo cliente, facilitando a gestão de envios e melhorando a experiência de compra.
Para isso, envie um POST ao endpoint /v1/customers/{id}/addressesAPI e inclua o ID do Cliente (customer_id) no path, junto com os atributos do endereço detalhados na tabela a seguir.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ -d '{ "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabalho", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" } }'
| Campo | Descrição | Obrigatoriedade |
zip_code | Código postal do endereço. | Obrigatório |
street_name | Nome da rua. | Obrigatório |
street_number | Número da rua. | Opcional |
name | Nome ou etiqueta do endereço (por exemplo: "Casa", "Trabalho"). | Opcional |
phone | Número de telefone associado ao endereço. | Opcional |
floor | Número do andar. | Opcional |
apartment | Identificador do apartamento. | Opcional |
comments | Comentários adicionais sobre o endereço. | Opcional |
city | Objeto com o nome da cidade. | Opcional |
state | Objeto com o ID e nome do estado ou província. | Opcional |
neighborhood | Objeto com o nome do bairro. | Opcional |
A resposta trará o seguinte resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabalho", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }
Obtenha os dados dos endereços de um cliente salvo através da API do Mercado Pago. É possível consultar todos os endereços associados ao cliente ou recuperar um endereço específico pelo ID. Para isso, utilize os endpoints abaixo.
Listar endereços
Consulte todos os endereços associados a um cliente. Envie um GET ao endpoint /v1/customers/{id}/addressesAPI com o ID do Cliente (customer_id) como parâmetro de path.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
A resposta será um array com todos os objetos de endereço salvos para o cliente:
json
[{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabalho", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }]
Obter endereço
Obtenha os dados de um endereço específico de um cliente. Envie um GET ao endpoint /v1/customers/{id}/addresses/{address_id}API com o ID do Cliente (customer_id) e o ID do Endereço (address_id) como parâmetros de path.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
A resposta trará o seguinte resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabalho", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }
Atualize os dados de um endereço existente de um cliente salvo através da API do Mercado Pago. Esta operação permite modificar qualquer atributo do endereço, como código postal, rua, número ou informações adicionais, e manter os dados do cliente sempre atualizados.
Envie um PUT ao endpoint /v1/customers/{id}/addresses/{address_id}API com o ID do Cliente (customer_id) e o ID do Endereço (address_id) como parâmetros de path, e os atributos a modificar no corpo da solicitação.
curl
curl -X PUT \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ -d '{ "zip_code": "04543907", "street_name": "Rua Funchal", "street_number": 418, "name": "Escritório Novo", "phone": "11912345678", "floor": "12", "apartment": "1201", "comments": "Edifício E-Tower, entrada pela recepção principal", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Vila Olímpia" } }'
| Atributo | Descrição |
zip_code | Código postal do endereço. |
street_name | Nome da rua. |
street_number | Número da rua. |
name | Nome ou etiqueta do endereço. |
phone | Número de telefone associado ao endereço. |
floor | Número do andar. |
apartment | Identificador do apartamento. |
comments | Comentários adicionais sobre o endereço. |
city | Objeto com o nome da cidade. |
state | Objeto com o ID e nome do estado ou província. |
neighborhood | Objeto com o nome do bairro. |
A resposta trará o seguinte resultado:
json
{ "id": "1162600213", "zip_code": "04543907", "street_name": "Rua Funchal", "street_number": 418, "name": "Escritório Novo", "phone": "11912345678", "floor": "12", "apartment": "1201", "comments": "Edifício E-Tower, entrada pela recepção principal", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Vila Olímpia" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T16:00:00.000Z" }
Se você não enviar o parâmetro customer_id ou address_id, receberá o seguinte erro:
json
{ "message": "missing customer id or address id" }
Elimina um endereço específico de um cliente salvo através da API do Mercado Pago. Esta operação permite manter atualizada a informação de endereços do cliente, eliminando aqueles que já não são necessários.
Envie um DELETE ao endpoint /v1/customers/{id}/addresses/{address_id}API com o ID do Cliente (customer_id) e o ID do Endereço (address_id) como parâmetros de path.
curl
curl -X DELETE \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
A resposta trará este resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabalho", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }