Registro com uma primeira cobrança com CVV
Se sua integração requer que o cliente faça uma primeira compra, você deverá:
- Criar o cliente para registrá-lo em seu sistema.
- Criar o pagamento utilizando o identificador do cliente e o token do cartão, criado na etapa de tokenização do meio de pagamento.
- Associar esse cartão ao cliente.
- Criar um perfil de pagamento a partir das informações do cliente, o que centralizará os meios de pagamento associados e permitirá reutilizá-los em cobranças futuras.
Para registrar um meio de pagamento com uma primeira cobrança com CVV, siga os passos abaixo.
Comece criando o cliente em seu sistema enviando um POST para o endpoint /v1/customersAPI, certificando-se de incluir na solicitação os dados coletados em seu frontend, especialmente o e-mail, que é obrigatório para criar o registro.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -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" }'
A resposta a esta solicitação retornará o identificador único deste cliente no parâmetro id, que você deverá usar nas etapas seguintes quando o customer_id for necessário.
json
{ "id": "000000001-sT93QZFAsfxU9P5", "email": "jhon@doe.com", "first_name": "Bruce", "last_name": "Wayne", "phone": { "area_code": 23, "number": 12345678 }, "identification": { "type": "DNI", "number": 12345678 }, "address": { "id": "1162600094", "zip_code": "SG1 2AX", "street_name": "Old Knebworth Ln" }, "description": "This is my description", "date_created": "2018-02-20T15:36:23.541Z", "metadata": { "source_sync": "source_ws" }, "default_address": "1162600094", "cards": [ {} ], "addresses": [ {} ], "live_mode": true }
Use a identificação do cliente e o token do cartão, obtido na etapa de tokenização do meio de pagamento, para criar o pagamento usando a API de Orders.
Para isso, envie um POST para o endpoint /v1/ordersAPI usando seu Access TokenChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação. e seguindo as indicações para os parâmetros obrigatórios detalhados na tabela abaixo.
curl
curl -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": "200.00", "external_reference": "ext_ref_1234", "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "amount": "200.00", "payment_method": { "id": "master", "type": "credit_card", "token": "1223123", "installments": 1 } } ] } }'
| Atributo | Tipo | Descrição | Obrigatoriedade |
Authorization | Header | Refere-se à sua chave privada, o Access Token de teste. | Obrigatório |
X-Idempotency-Key | Header | Chave de idempotência. Esta chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no cabeçalho da sua solicitação, como um UUID V4 ou strings aleatórias. | Obrigatório |
processing_mode | Body. String | Modo de processamento da order. Os valores possíveis são: automatic, para criar e processar a order em modo automático. automatic_assync, para criar a order com lógica de tentativas. Para mais informações, acesse Modo de processamento de Orders. | Obrigatório |
total_amount | Body. String | Valor total da transação. | Obrigatório |
payer.customer_id | Body. String | Identificador do cliente criado na etapa anterior. | Obrigatório |
transaction.payments.payment_method.id | Body. String | Identificador do meio de pagamento. Neste caso, é a bandeira de cada cartão. Para mais informações, consulte a lista de Meios de pagamento disponíveis. | Obrigatório |
transaction.payments.payment_method.type | Body. String | Tipo de meio de pagamento. Para pagamentos com cartões de crédito, deve ser credit_card, para pagamentos com cartão de débito, deve ser debit_card, e para pagamentos com cartões pré-pagos, prepaid_card. | Obrigatório |
payment_method.token | Body. String | Token do cartão, obtido na etapa de tokenização do meio de pagamento. | Obrigatório |
Em caso de sucesso, a resposta será semelhante ao exemplo abaixo, e o primeiro pagamento terá sido processado.
json
{ "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "200.00", "total_paid_amount": "200.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": "200.00", "paid_amount": "200.00", "reference_id": "0002yjis6j", "status": "processed", "status_detail": "accredited", "payment_method": { "id": "elo", "type": "credit_card", "token": "1223123", "installments": 1 } } ] } }
Uma vez que o primeiro pagamento tenha sido processado e o meio de pagamento validado, você deverá usar o mesmo token do cartão enviado no pagamento para associá-lo ao cliente previamente criado, e assim poder armazenar as informações para utilizá-las em pagamentos posteriores.
Para isso, envie um POST para o endpoint /v1/customers/{customer_id}/cardsAPI, incluindo o customer_id no path da requisição e o token do cartão no body, como indicado a seguir. Certifique-se de enviar também seu Access TokenChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação..
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/cards' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d '{ "token": "1223123" }'
Se a solicitação foi bem-sucedida, a resposta retornará um id, que é o identificador do cartão. Você deverá usá-lo para finalizar a etapa de registro do meio de pagamento a partir de uma primeira cobrança.
json
{ "id": 1562188766852, "expiration_month": 6, "expiration_year": 2023, "first_six_digits": 423564, "last_four_digits": 5682, "payment_method": { "id": "visa", "name": "visa", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/visa.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/visa.gif" }, "date_created": "2019-07-03T21:15:35.000Z", "date_last_updated": "2019-07-03T21:19:18.000Z", "customer_id": "448870796-7ZjwhKGxILixxN", "user_id": 448870796, "live_mode": true }
Para armazenar os dados do cliente e seu cartão para pagamentos posteriores, é necessário criar um perfil de pagamento. Este perfil será a estrutura que conterá os dados de pagamento a serem utilizados em seu sistema e facilitará seu reaproveitamento para próximas cobranças.
Para criar o perfil de pagamento do cliente, envie um POST para o endpoint /v1/customers/{customer_id}/payment-profiles. No path da requisição, inclua o customer_id obtido ao criar o cliente. No body, informe o id do cartão gerado ao associar o cartão ao cliente. A seguir, você pode ver na tabela como enviar cada um dos parâmetros necessários.
curl
curl --location 'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/payment-profiles' \ --header 'X-Idempotency-Key: {{X_IDEMPOTENCY_KEY}}' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{ "description": "Test", "payment_methods": [ { "id": "master", "type": "credit_card", "card_id": {{CARD_ID}}, "default_method": false } ] }'
| Campo | Tipo e descrição | Obrigatoriedade |
customer_id | Path. Identificador do cliente, obtido ao criar o cliente na etapa anterior. | Obrigatório |
description | Body, string. Descrição do perfil de pagamento. Recomendamos usar este campo para categorizar tipos de serviços contratados, planos ou a frequência do modelo de negócio. | Opcional |
payment_methods | Body, object. Contém as informações do meio de pagamento. Durante a criação do perfil, não permite mais de dois meios de pagamento. Quando há dois cartões, apenas um será identificado com o token, e o outro deverá ser identificado com o card_id. Aceita no máximo dois cartões (crédito ou débito). | Obrigatório |
payment_methods.id | Body, string. Identificador do meio de pagamento ou bandeira do cartão. Exemplo: visa, master. | Obrigatório |
payment_methods.type | Body, string. Tipo de meio de pagamento. Os valores podem ser credit_card (cartão de crédito), debit_card (cartão de débito) ou prepaid_card (cartão pré-pago). | Obrigatório |
payment_methods.card_id | Body, string. Identificador do cartão do cliente, obtido na etapa anterior. | Obrigatório |
payment_methods.default_method | Body, boolean. Identifica se o meio de pagamento é o padrão para realizar as tentativas de pagamento para esse cliente. | Opcional |
Se a solicitação for bem-sucedida, a resposta retornará status = READY e o identificador do perfil de pagamento para esse cliente, no parâmetro id. Este profile_id deverá ser usado para processar os pagamentos com a API de Orders.
json
{ "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T14:03:28.653Z", "description": "Test payment profile", "max_day_overdue": 5, "statement_descriptor": "Test Descriptor", "status": "READY", "sequence_control": "AUTO", "payment_methods": [ { "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true } ] }
Se necessário, posteriormente será possível atualizar o perfil de pagamento do cliente, incluir novos meios de pagamento ou até mesmo excluí-lo. Consulte Gestão de perfis para mais informações.