Para que a estratégia de retentativas funcione, seu sistema precisa saber imediatamente quando um pagamento falha e por qual motivo. Para isso, é necessário que você configure suas notificações Webhooks e receba alertas sobre a criação ou atualização de um pagamento, o que permitirá que você tome as ações pertinentes.

Certifique-se de ter configurado suas notificações Webhooks para o tópico Pagamentos (payment). Se ainda não fez isso, siga o passo a passo da documentação de notificações Webhooks.

Diante de eventos de criação ou atualização de um pagamento, o Mercado Pago enviará uma notificação com o seguinte formato:

json
Copiar
{
  "id": 12345,
  "live_mode": true,
  "type": "payment",
  "date_created": "2015-03-25T10:04:58.396-04:00",
  "user_id": 44444,
  "api_version": "v1",
  "action": "payment.created",
  "data": {
    "id": "132260878091"
  }
}

Esta notificação contém apenas o ID do pagamento, não o seu status. Ao recebê-la, seu servidor deve consultar imediatamente a API de Pagamentos para obter os detalhes completos.

Para consultar o status de um pagamento, envie uma requisição /v1/payments/{id}GET utilizando o ID recebido na notificação.

curl -X GET \
  'https://api.mercadopago.com/v1/payments/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Na resposta, localize os dois campos que indicam o código de rejeição e determinam sua próxima ação:

Nem todas as rejeições devem ser tratadas da mesma forma. A categorização correta do erro a partir do seu status_detail determina se é necessário aplicar uma lógica de retentativa ou se é necessário acionar o pagador.

De acordo com sua natureza, as rejeições se agrupam em três categorias:

• Soft Declines (erros temporários): a rejeição é temporária e há alta probabilidade de aprovação em uma nova tentativa. Vale a pena reprocessar seguindo uma cadência.
• Hard Declines (erros permanentes): a rejeição não se resolve reprocessando, e insistir pode afetar sua reputação junto aos adquirentes. Não reprocesse e o cliente deve atualizar seu meio de pagamento.
• Erros de preenchimento ou configuração: requerem uma correção prévia, seja do cliente, seja da sua integração. Reprocesse somente após corrigir o dado ou a configuração.

Veja como reconhecer o tipo de erro e quais ações implementar a seguir.

Na maioria dos fluxos, o Mercado Pago não contata o cliente final em seu nome. O gerenciamento da comunicação em casos de rejeição é responsabilidade do estabelecimento e é tão importante quanto a retentativa técnica.

Por isso, é necessário que você defina uma estratégia de comunicação levando em conta os seguintes pontos:

• Defina uma janela de recuperação: determine por quanto tempo o cliente tem para resolver o motivo do rejeito do pagamento antes de suspender o serviço.

• Segmente a comunicação por tipo de erro:

  • Soft Declines: use um tom de baixa fricção. Comunique que houve um problema temporário e que o reprocessamento será feito automaticamente.
  • Hard Declines: use um tom de urgência. Informe que o serviço corre risco de suspensão e solicite a atualização imediata do meio de pagamento.

• Forneça um link de atualização seguro: direcione o cliente a um portal seguro onde ele possa atualizar seu meio de pagamento; nunca solicite seus dados por outros meios. Quando o cliente realizar a atualização, execute a cobrança pendente imediatamente.

Para mais informações sobre como melhorar a aprovação de pagamentos, consulte as recomendações para melhorar a aprovação.