Gestão de perfis
Após concluir as configurações iniciais, você poderá acessar um conjunto de chamadas voltadas à gestão dos perfis criados.
Nesta seção, apresentamos as principais operações disponíveis para administrar um perfil e como executá-las.
Esta operação permite consultar um perfil de pagamento associado a um cliente específico utilizando um ID, o que permite acesso a todas as informações registradas, por exemplo, quando é necessário confirmar os dados do perfil antes de realizar um novo pagamento ou exibir ao usuário as informações do meio de pagamento armazenado.
Para isso, envie um GET ao endpoint Consultar um perfil de pagamento específicoAPI considerando os parâmetros listados na tabela abaixo do código.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{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 um GET ao endpoint Consultar lista de perfis de pagamentoAPI considerando os parâmetros listados na tabela abaixo do código.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles?limit=50&status=READY' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{access_token}}'
| Atributo | Tipo | Descrição | Obrigatoriedade |
customer_id | Header. 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 um POST ao endpoint Adicionar meio de pagamento a um perfilAPI considerando os parâmetros listados na tabela abaixo do código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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 que está sendo 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 um DELETE ao endpoint Excluir meio de pagamento do perfilAPI considerando os parâmetros listados na tabela abaixo do código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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 |
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 um POST ao endpoint Cancelar perfil de pagamentoAPI considerando os parâmetros listados na tabela abaixo do código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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.