Recursos para IA

Modelo de integração

Checkout Transparente agora processa pagamentos com Orders. Se trata de uma API projetada para simplificar seu desenvolvimento com o Mercado Pago: com uma única integração, você poderá acessar diversas soluções de pagamento.

Além disso, a API torna o código de integração mais intuitivo e fornece mensagens de erro mais detalhadas, facilitando o processo de desenvolvimento.

Diferenças no processamento

Anteriormente, os pagamentos via Checkout Transparente eram processados exclusivamente pela API de Pagamentos. Agora, também é possível processá-los por meio de Orders, que oferece uma alternativa eficiente e simples para a integração.

Veja abaixo as principais diferenças entre as duas opções.

Funcionalidade	API de Pagamentos	API de Orders
Processamento do pagamento	Automático (crie e processe sua transação).	Automático ou manual (escolhendo quando processar a sua transação).
Transações	Uma transação por requisição.	Múltiplas transações por requisição.
Operações	Pagamentos online.	Pagamentos online e Pagamentos presenciais (Point do Mercado Pago).
Notificações	Configuração avançada por `notification_url`.	Configuração mais simples a partir da seção de Notificações em Suas integrações.
Validação dos erros	Retorna um erro por vez.	Retorna uma lista com todos os erros na requisição.

Modos de processamento de Orders

Uma order de pagamentos online pode ser criada para ser processada de dois modos: Modo automático e Modo manual.

A definição do modo de processamento será realizada no momento da criação da order, por meio do parâmetro processing_mode. Seu valor deve ser automatic para processamentos automáticos, ou manual para processar a order manualmente. Consulte abaixo as características de cada modo.

O capture_mode indica como a order será processada e determina se a resposta da criação terá um status final ou intermediário. Só é aplicável quando processing_mode for automatic. No modo manual, o capture_mode define se será necessário capturar posteriormente o valor previamente autorizado. Para mais detalhes, consulte a Referência de APIAPI.

O modo automático é o modo padrão da aplicação. Por meio dele, a transação é concluída em uma única etapa e as modificações são limitadas. É indicado para cenários em que todas as informações necessárias para concluir a transação já estão disponíveis no momento da criação da order, incluindo dados do comprador, itens e informações do meio de pagamento devidamente tokenizadas.

Nesse fluxo, todas as informações são enviadas em uma única requisição, e a API é responsável por orquestrar a comunicação com as camadas processadoras. O status retornado na resposta da criação da order dependerá da configuração do parâmetro capture_mode.

Para criar a order no modo automático, defina o campo processing_mode, responsável por definir o formato de criação e processamento da transação, como automatic. No objeto transactions, o nó payments deve conter o payment_method completo, incluindo o token do cartão gerado via SDK ou API, conforme o exemplo a seguir:

curl
{
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "order_oneshot_123",
  "total_amount": "1000.00",
  "payer": {
    "email": "comprador@teste.com"
  },
  "transactions": {
    "payments": [
      {
        "amount": "1000.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "677859ef5f18ea7e3a87c41d02c3fbe3",
          "installments": 12
        }
      }
    ]
  }
}

A API retorna o objeto da order com o status já atualizado da transação (por exemplo, processed ou accredited):

json
{
  "id": "01JC1KVZ0WJY8Y4WA7MZAD5S2T",
  "status": "processed",
  "status_detail": "accredited",
  "transactions": {
    "payments": [
      {
        "id": "pay_01JC1KVZ0WJY8Y4WA7MZG3A8F2",
        "status": "processed",
        "status_detail": "accredited",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "installments": 12
        }
      }
    ]
  }
}

As operações permitidas são:

Criar e processar order: responsável pela criação da order já com o processamento da transação simultâneo.
Obter order: permite obter informações sobre uma order, incluindo o seu status em tempo real.
Buscar order: permite buscar orders de forma massiva, utilizando diversos filtros e informações de paginação.
Capturar order: possibilita a captura do valor autorizado de uma order. Essa opção só é válida para cartões de crédito.
Cancelar order: responsável pelo cancelamento de uma order já existente, mas que ainda não foi processada.
Reembolsar order: possibilita o estorno total ou parcial de um pagamento. A order será reembolsada totalmente se todas as transações forem estornadas por completo.
- Reembolso total: não deverá ser indicado o valor a ser reembolsado no body da requisição, que deve ser enviado vazio.
- Reembolso parcial: deverá ser especificada a quantia a ser reembolsada no body da requisição junto com o ID da transação. Todas as outras transações permanecerão como estão e somente a transação alterada será reembolsada.