Recursos para IA
Pagamentos únicos com cartão salvo
Os pagamentos únicos com cartões salvos (Card on File) são pagamentos nos quais os dados registrados do meio de pagamento são utilizados para realizar cobranças ocasionais sem a necessidade de o usuário reinserir as informações do cartão.
Trata-se de pagamentos que não têm uma recorrência, mas dependem de uma ação do comerciante ou do cliente para serem executados, como cobranças automáticas em pedágios ou pagamentos em apps de delivery com cartões salvos, respectivamente.
Para processar pagamentos únicos com cartões salvos, envie um POST para o endpoint /v1/ordersAPI. Você deverá enviar 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 as informações detalhadas abaixo para este tipo de pagamento.
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", "external_reference": "ext_ref_1234", "total_amount": "1000.00", "processing_mode": "automatic_async", "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "amount": "1000.00", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943", "retries": 3 }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }'
| Atributo | Tipo | Descrição | Obrigatoriedade |
Authorization | Header | Faz referência à sua chave privada, o 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.. | 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, associada à solução do Mercado Pago para a qual é criada. Para pagamentos online com cartões, o único valor possível é online. | Obrigatório |
external_reference | Body. String | É uma referência externa da order. Pode ser, por exemplo, um hashcode do Banco Central, funcionando como identificador de origem da transação. Este campo deve ter no máximo 64 caracteres e estes só podem ser números, letras, hífens (-) e underscores (_). Caracteres especiais como ([ ], (), '', @) não são permitidos. | Obrigatório |
total_amount | Body. String | Valor total da transação. | 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_async, para criar a order com lógica de tentativas. Para mais informações, acesse Modos de processamento de Orders. | Opcional |
payer.customer_id | Body. String | Identificador do cliente que realizará o pagamento. É obtido na etapa Registrar meio de pagamento, no momento de criar o cliente, seja um registro com uma primeira cobrança ou um registro para pagamentos futuros. | Obrigatório |
transactions.payments.amount | Body. String | Valor da transação. | Obrigatório |
transaction.payments.automatic_payments.payment_profile_id | Body. String | Identificador do perfil de pagamento do cliente. Obtido na etapa Registrar meio de pagamento, ao criar o perfil de pagamento, seja um registro com uma primeira cobrança ou um registro para pagamentos futuros. | Obrigatório |
transaction.payments.automatic_payments.retries | Body. Integer | Número de vezes em que o pagamento será tentado novamente em caso de falha inicial. Deve ser um número entre 1 e 5. É um campo que só será permitido caso tenha sido definido processing_mode=automatic_async. Adicionalmente, se o perfil de pagamento do cliente tiver configurado o campo max_day_overdue, a configuração de tentativas estabelecida para retries não terá prioridade. | Opcional |
transaction.payments.stored_credentials.payment_initiator | Body. String | Identifica quem inicia a transação. Os valores possíveis são: - customer, quando a transação é iniciada pelo cliente. - merchant, quando a transação é iniciada pelo vendedor. | Obrigatório |
transaction.payments.stored_credentials.reason | Body. String | Identificador do tipo de pagamento, que é a razão pela qual está sendo armazenado. O único valor possível para pagamentos únicos com cartões salvos é card_on_file. | Opcional |
transaction.payments.stored_credentials.previous_transaction_reference | Body. String | Código de referência da transação anterior à que está sendo processada, se houver. Deve ser enviado a partir do segundo pagamento processado para o mesmo cliente. | Obrigatório quando first_payment: false |
transaction.payments.stored_credentials.first_payment | Body. Boolean | Indica se se trata do processamento de um primeiro pagamento (true) ou se é um pagamento posterior (false). | Opcional |
Se a solicitação for enviada corretamente, o pagamento terá sido criado e a resposta será semelhante ao exemplo abaixo.
json
{ "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE", "processing_mode": "automatic_async", "external_reference": "ext_ref_1234", "total_amount": "200.00", "country_code": "MEX", "user_id": "1245621468", "created_date": "2024-09-02T22:04:01.880469Z", "last_updated_date": "2024-09-02T22:04:04.429289Z", "type": "online", "status": "processing", "status_detail": "processing", "capture_mode": "automatic_async", "integration_data": { "application_id": "4599991948843755" }, "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24", "reference_id": "74e9f7137a3246d3a3ad607c82da9880", "amount": "200.00", "status": "processing", "status_detail": "processing", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943" }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }
Você pode consultar o detalhe dos status possíveis a serem retornados na resposta acessando as seções Status da order e Status da transação, respectivamente. Adicionalmente, você pode consultar os Possíveis erros ao enviar esta solicitação.