Registro para pagamentos futuros
Se sua integração não requer uma compra inicial e você só precisa cadastrar os usuários, será necessário armazenar os cartões para pagamentos futuros, sejam recorrentes, one-click ou débitos automáticos. Por isso, após a tokenização do meio de pagamento, você deverá criar um perfil de pagamento para o cliente.
Este perfil centraliza os meios de pagamento associados e permite reutilizá-los em cobranças futuras. A API de Perfis valida automaticamente cada meio, evitando a realização de pagamentos de validação manuais. Em caso de recusa, tenta novamente com outros meios para melhorar a taxa de aprovação.
Para registrar o meio de pagamento na API de Perfis e utilizá-lo em pagamentos futuros, 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 }
Para armazenar os dados do cliente e seu cartão para pagamentos futuros, é necessário criar um perfil de pagamento. Este perfil permitirá validar se o meio de pagamento é útil para realizar cobranças de forma automática e será a estrutura que conterá os dados de pagamento a serem utilizados em seu sistema. Você deverá ter o customer_id gerado na etapa anterior e o card_token do cartão, gerado durante a tokenização do meio de pagamento.
Para criar o perfil de pagamento do cliente previamente registrado, 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 token do cartão, gerado ao tokenizar o meio de pagamento. A seguir, você pode ver na tabela como enviar cada um dos parâmetros necessários.
curl
curl --location --globoff '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": "description", "max_day_overdue": 5, "statement_descriptor": "statement_descriptor", "payment_methods": [ { "id": "{{bandera_de_la_tarjeta}}", "type": "credit_card", "token": "{{card_token}}", "default_method": true } ] }'
| 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 |
max_day_overdue | Body, integer. Define a quantidade de dias para realizar novas tentativas de processamento do pagamento em caso de falha ou rejeição inicial. Por exemplo, se você enviar "5" como valor, novas tentativas de processamento serão feitas para os próximos 5 dias após a primeira falha. Caso o pagamento seja processado antes dos dias definidos, a lógica de tentativas será interrompida. Valor entre 1 e 10. | Opcional |
statement_descriptor | Body, string. Descrição que aparecerá no extrato do meio de pagamento do cliente. Útil para identificar a transação. Exemplo: MERCADOPAGO. | 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. Se houver mais de um meio, 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.token | Body, string. Token que identifica o cartão do cliente, gerado durante a tokenização do meio de pagamento. Tem um comprimento mínimo de 32 caracteres e um comprimento máximo de 33. | 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 API de Perfis realizará uma validação automática do meio de pagamento e retornará status = READY junto com 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, "first_six_digits": 123456, "last_four_digits": 4321, "status": "READY", "default_method": true } ] }
A resposta também conterá as informações relativas ao meio de pagamento, incluindo o campo payment_method_id, que será utilizado pela mesma API para atualizar automaticamente o registro do cartão para o cliente.
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.