Gestão de perfis
Após concluir as configurações iniciais, você poderá acessar um conjunto de chamadas voltadas à gestão dos perfis.
Nesta seção, apresentamos as principais operações disponíveis para administrar um perfil e como executá-las.
Para armazenar os dados do cliente e do cartão para pagamentos futuros, é necessário criar um perfil de pagamento. Esse perfil funcionará como a estrutura que armazena os dados de pagamento utilizados pelo seu sistema, facilitando seu reaproveitamento em cobranças futuras.
Para criar o perfil de pagamento do cliente, envie uma requisição ao endpoint Criar perfil de pagamento para o clientePOST considerando os parâmetros listados na tabela abaixo do código. 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.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "description": "Payment description", "payment_methods": [ { "id": "master", "type": "credit_card", "card_id": 1234567890, "default_method": false } ] }'
| Atributo | Tipo | Descrição | Obrigatoriedade |
customer_id | Path. String | 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. É possível combinar cartões de crédito e 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. Long | 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 |
AUTO para o campo sequence_control. Perfis criados com o valor MANUAL geram conflitos com o campo stored_credential.previous_transaction_reference, o que pode impedir a execução das cobranças.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": "Payment description", "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 } ] }
Esta operação permite consultar, a partir de um ID, o perfil de pagamento associado a um cliente específico, retornando todas as informações registradas. É útil, por exemplo, para confirmar os dados do perfil antes de um novo pagamento ou para exibir ao usuário as informações do meio de pagamento armazenado.
Para isso, envie uma requisição ao endpoint Consultar um perfil de pagamento específicoGET considerando os parâmetros listados na tabela abaixo do código.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descrição | Obrigatoriedade |
customer_id | Path. String | Identificador único do cliente cujo perfil de pagamento está sendo consultado. | Obrigatório |
payment_profile_id | Path. String | Identificador único do perfil de pagamento, associado ao cliente. | Obrigatório |
Em caso de sucesso, a resposta retornada seguirá o formato do exemplo abaixo.
json{ "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T14:03:28.653Z", "description": "Payment description", "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 } ] }
Esta operação permite consultar a lista de perfis de pagamento associados a um cliente por meio do seu ID, sendo útil quando é preciso identificar quais perfis o cliente possui para escolher qual deles será utilizado em pagamentos posteriores.
Para isso, envie uma requisição ao endpoint Consultar lista de perfis de pagamentoGET considerando os parâmetros listados na tabela abaixo do código.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles?limit=50&status=READY' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descrição | Obrigatoriedade |
customer_id | Path. String | Identificador único do cliente para o qual os perfis de pagamento estão sendo consultados. | Obrigatório |
limit | Query. Integer | Limite de paginação. Especifica o número máximo de registros que você deseja obter na resposta. Deve ser um valor numérico entre 1 e 100, sendo 50 o valor aplicado por padrão. | Opcional |
offset | Query. Integer | Offset de paginação. Determina o ponto inicial a partir do qual os registros devem ser obtidos. Deve ser um valor numérico maior ou igual a zero (0). | Opcional |
status | Query. String | Status atual do perfil de pagamento. Deve enviá-lo caso deseje filtrar os perfis pelo status. | Opcional |
Em caso de sucesso, a resposta retornada seguirá o formato do exemplo abaixo.
json{ "paging": { "total": 10, "total_pages": 100, "offset": 1, "limit": 10 }, "data": [ { "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T15:03:28.653Z", "description": "Simple description", "max_day_overdue": 5, "statement_descriptor": "Statement description", "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 } ] } ] }
Esta operação permite adicionar um novo meio de pagamento ao perfil do cliente ou atualizar um existente, incluindo a possibilidade de ajustar o campo default_method para true ou false, definindo assim se ele será ou não o meio de pagamento padrão.
Para adicionar um meio de pagamento, envie uma requisição ao endpoint Adicionar meio de pagamento a um perfilPOST considerando os parâmetros listados na tabela abaixo do código.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "id": "{{bandeira_cartao}}", "type": "credit_card", "token": "{{card_token}}", "default_method": true }'
| Atributo | Tipo | Descrição | Obrigatoriedade |
X-Idempotency-Key | Header. String | Chave de idempotência. Permite repetir solicitações com segurança, evitando que a mesma ação seja processada mais de uma vez. Recomendamos usar um UUID V4 ou strings aleatórias. | Obrigatório |
Authorization | Header. String | Chave privada utilizada para autenticar as requisições. Utilize seu Access Token de teste no ambiente de desenvolvimento e seu Access Token produtivo no ambiente de produção. | Obrigatório |
customer_id | Path. String | Identificador único do cliente ao qual pertence o perfil de pagamento a ser modificado. | Obrigatório |
payment_profile_id | Path. String | Identificador único do perfil de pagamento a modificar, associado ao cliente. | Obrigatório |
id | Body. String | Identificador do meio de pagamento selecionado. Para pagamentos com cartão, indique a bandeira (visa, master, debmaster, debvisa). | Obrigatório |
type | Body. String | Tipo do meio de pagamento selecionado: credit_card, debit_card, prepaid_card. | Obrigatório |
token | Body. String | Token seguro que identifica o meio de pagamento. É obrigatório em transações com cartão e deve ter entre 32 e 33 caracteres. | Obrigatório para cartão |
card_id | Body. Long | ID do cartão associado ao meio de pagamento. | Obrigatório |
default_method | Body. Boolean | Define se este meio será utilizado como padrão em futuras tentativas de pagamento. | Opcional |
Em caso de sucesso, a resposta retornada seguirá o formato do exemplo abaixo.
json{ "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true }
Ao adicionar um meio de pagamento a um perfil, a API realiza automaticamente sua validação para verificar se ele poderá ser utilizado em cobranças futuras. O resultado dessa validação é indicado pelo campo status, que mostra a situação atual do meio de pagamento. Saiba mais sobre os status do meio de pagamento consultando nossa documentação.
Esta operação permite excluir um meio de pagamento de um perfil, o que pode ser necessário quando o usuário opta por remover um cartão que não deseja mais utilizar ou quando o meio deixa de ser válido para cobranças futuras.
Para isso, envie uma requisição ao endpoint Excluir meio de pagamento do perfilDELETE considerando os parâmetros listados na tabela abaixo do código.
curlcurl -X DELETE \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods/{{payment_method_id}}' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descrição | Obrigatoriedade |
X-Idempotency-Key | Header. String | Permite repetir solicitações de forma segura sem risco de executar a mesma ação duas vezes por engano. Use um valor exclusivo (por exemplo, UUID v4 ou string aleatória) para garantir a unicidade da requisição. | Obrigatório |
Authorization | Header. String | Chave privada utilizada para autenticar as requisições. Utilize seu Access Token de teste no ambiente de desenvolvimento e seu Access Token produtivo no ambiente de produção. | Obrigatório |
customer_id | Path. String | Identificador único do cliente ao qual pertence o perfil de pagamento que está sendo modificado. | Obrigatório |
payment_profile_id | Path. String | Identificador único do perfil de pagamento do qual o meio de pagamento será excluído. | Obrigatório |
payment_method_id | Path. String | Identificador único do meio de pagamento a excluir do perfil, obtido na resposta à criação do perfil. | Obrigatório |
Em caso de sucesso, a resposta retornará um status 202, o que confirma seu correto processamento.
Esta operação possibilita cancelar um perfil de pagamento vinculado a um cliente por meio dos respectivos IDs, sendo utilizada quando o perfil não será mais utilizado para cobranças futuras ou quando é preciso registrar um novo perfil desde o início.
Para isso, envie uma requisição ao endpoint Cancelar perfil de pagamentoPOST considerando os parâmetros listados na tabela abaixo do código.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/cancel' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descrição | Obrigatoriedade |
X-Idempotency-Key | Header. String | Permite repetir solicitações de forma segura sem risco de executar a mesma ação duas vezes por engano. Use um valor exclusivo (por exemplo, UUID v4 ou string aleatória) para garantir a unicidade da requisição. | Obrigatório |
Authorization | Header. String | Chave privada utilizada para autenticar as requisições. Utilize seu Access Token de teste no ambiente de desenvolvimento e seu Access Token produtivo no ambiente de produção. | Obrigatório |
customer_id | Path. String | Identificador único do cliente cujo perfil de pagamento está sendo cancelado. | Obrigatório |
payment_profile_id | Path. String | Identificador único do perfil de pagamento a cancelar, associado ao cliente. | Obrigatório |
Em caso de sucesso, a resposta retornará um status 202, o que confirma seu correto processamento.
Se deseja consultar os principais status que um perfil de pagamento pode ter, assim como os status dos seus meios de pagamento associados, acesse a documentação.