Recursos para IA
Pagamentos com recorrência programada
Os pagamentos com recorrência programada permitem realizar cobranças automáticas em intervalos definidos, utilizando os dados previamente salvos do meio de pagamento sem a necessidade de uma nova interação do usuário. A lógica de recorrência é definida e gerenciada pelo vendedor através da criação dos pagamentos, adaptando-se às necessidades do negócio.
Este modelo é indicado para cobranças recorrentes, como assinaturas, planos e serviços contínuos.
Para processar pagamentos com recorrência programada, 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, "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "00000000000", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "monthly" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "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.automatic_payments.subscription.id | Body. String | Identificador da assinatura. Sugerimos que este valor seja composto pelo collector + um ID de assinatura único por usuário. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.sequence.number | Body. Integer | Indica o número do pagamento subsequente. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.sequence.total | Body. Integer | Indica o número total de pagamentos da assinatura. Para assinaturas permanentes, deve ser null. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.invoice.id | Body. String | Identificador da invoice associada ao ciclo de cobrança. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.invoice.billing_date | Body. String | Data de faturamento correspondente ao ciclo da assinatura. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.invoice.period.interval | Body. Number | Intervalo de tempo entre cada cobrança. | Obrigatório se sequence_control for manual |
transaction.payments.automatic_payments.subscription.invoice.period.type | Body. String | Tipo de período da recorrência. Os valores possíveis são daily, weekly ou monthly. | Obrigatório se sequence_control for manual |
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 com recorrência programada é recurring. Se você enviar este campo e o perfil de pagamento tiver definido o campo sequence_control como auto, não é necessário enviar o nó automatic_payments.subscription, pois as informações da recorrência serão gerenciadas automaticamente pelo sistema. Acesse Gerenciar pagamentos com recorrência programada para mais informações | 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", "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "invoice-id", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "month" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "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 Erros possíveis ao enviar esta solicitação.
Gerenciar pagamentos com recorrência programada
Quando você cria um pagamento com recorrência programada, certos campos vinculados à frequência do pagamento são necessários para melhorar a taxa de aprovação. Na API de Orders, esses campos são os contidos no nó subscription.
Com o apoio da API de Perfis, o gerenciamento dessas informações pode ser feito de duas formas: automática ou manual.
Para automatizar o gerenciamento das informações relativas à recorrência do pagamento e evitar enviar essas informações manualmente, você deve:
- Definir o campo
sequence_controldo perfil de pagamento do cliente comoauto. Se você precisar de mais informações sobre como fazer isso, acesse nossa Referência de API. - Criar o pagamento enviando o valor
recurringpara o campotransaction.payments.stored_credentials.reason.
Desta forma, não será necessário enviar as informações contidas no nó transaction.payments.automatic_payments.subscription, pois serão gerenciadas automaticamente pelo sistema.