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. Ao processar a order, o cartão será associado ao cliente e o perfil de pagamento será criado automaticamente.
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 uma requisição ao endpoint /v1/customersPOST, certificando-se de incluir na solicitação os dados coletados em seu frontend, especialmente o e-mail, que é obrigatório para criar o registro.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_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 }
Ao criar o primeiro pagamento pela API de Orders, você pode armazenar o cartão e gerar automaticamente o perfil de pagamento do cliente na mesma requisição. Para ativar esse comportamento, envie stored_credential.store_payment_method com o valor true. Dessa forma, não é necessário associar o cartão nem criar o perfil por meio de requisições adicionais.
Para isso, envie uma requisição ao endpoint /v1/ordersPOST usando seu Access TokenChave privada utilizada no backend para autenticar as solicitações às APIs do Mercado Pago. Nunca deve ser compartilhada nem exposta no frontend. e seguindo as indicações para os parâmetros obrigatórios detalhados na tabela abaixo.
curlcurl -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 }, "stored_credential": { "store_payment_method": true, "payment_initiator": "customer", "reason": "recurring", "first_payment": true } } ] } }'
| 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 |
type | Body. String | Tipo de order. Para pagamentos online, o valor deve ser online. | 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, e automatic_async, 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 |
transactions.payments.amount | Body. String | Valor do pagamento. | Obrigatório |
transactions.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 |
transactions.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, debit_card; e para pagamentos com cartões pré-pagos, prepaid_card. | Obrigatório |
transactions.payments.payment_method.token | Body. String | Token do cartão, obtido na etapa de tokenização do meio de pagamento. | Obrigatório |
transactions.payments.payment_method.installments | Body. Integer | Quantidade de parcelas selecionada para o pagamento. | Obrigatório |
transactions.payments.stored_credential.store_payment_method | Body. Boolean | Indica se o meio de pagamento deve ser armazenado para uso em cobranças futuras. Para criar o perfil automaticamente, envie true. | Obrigatório |
transactions.payments.stored_credential.payment_initiator | Body. String | Indica quem iniciou o pagamento. Para a primeira cobrança com CVV, envie customer. | Obrigatório |
transactions.payments.stored_credential.reason | Body. String | Indica o motivo pelo qual o meio de pagamento está sendo armazenado. Para pagamentos recorrentes, envie recurring. | Obrigatório |
transactions.payments.stored_credential.first_payment | Body. Boolean | Indica se este é o primeiro pagamento da recorrência. Para este fluxo, envie true. | Obrigatório |
Em caso de sucesso, a resposta será semelhante ao exemplo abaixo, o primeiro pagamento terá sido processado e o perfil de pagamento do cliente terá sido criado.
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 }, "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943" }, "stored_credential": { "store_payment_method": true, "payment_initiator": "customer", "reason": "recurring", "first_payment": true } } ] } }
A resposta retornará de forma síncrona o identificador do perfil de pagamento no campo transactions.payments.automatic_payments.payment_profile_id.
payment_profile.updated indicar que o perfil está no status READY. Para receber este evento, consulte Configurar notificações de Perfis de Pagamento.Para consultar os principais status que um perfil de pagamento pode ter, assim como os status dos seus meios de pagamento associados, acesse Status do perfil e do meio de pagamento. Se necessário, você poderá atualizar o perfil, incluir novos meios de pagamento ou excluí-lo. Consulte Gestão de perfis para mais informações.