Processar pagamentos (via Advanced Payments API)
Com a Advanced Payments API, os pagamentos são processados a partir do payer_token obtido na vinculação, debitando o valor diretamente da carteira do comprador. Antes de processar pagamentos, é necessário ter concluído o fluxo de vinculação e obtido o payer_token. Caso ainda não o tenha feito, consulte a seção Configurar a vinculação.
Para processar o pagamento, envie uma solicitação ao endpoint /v1/advanced_paymentsPOST, incluindo seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o token de pagamento do comprador.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/advanced_payments' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "wallet_payment": { "transaction_amount": 550, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payer": { "token": "PAYER_TOKEN", "type_token": "wallet-tokens" }, "capture": true }'
Consulte na tabela abaixo as descrições dos parâmetros que são obrigatórios na requisição e daqueles que, embora sejam opcionais, possuem alguma particularidade importante de ser destacada.
| Parâmetro | Tipo | Descrição | Obrigatoriedade |
X-Idempotency-Key | Header | Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando a criação de dois pagamentos idênticos. Use um valor exclusivo no header da requisição, como um UUID V4 ou uma string aleatória. | Obrigatório |
Authorization | Header | Refere-se ao Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`.. | Obrigatório |
X-Meli-Session-Id | Header | Identificador do dispositivo do comprador no momento da compra, utilizado para melhorar a segurança e aumentar a taxa de aprovação do pagamento. | Opcional |
wallet_payment.transaction_amount | Body. Number | Valor do pagamento. | Obrigatório |
wallet_payment.description | Body. String | Breve descrição do pagamento. | Opcional |
wallet_payment.external_reference | Body. String | Referência personalizada do vendedor, usada para correlacionar um pagamento do Mercado Pago com um pedido interno. | Opcional |
wallet_payment.statement_descriptor | Body. String | Texto que aparece no extrato do comprador junto com o valor e a data da cobrança. Aceita no máximo 50 caracteres alfanuméricos. | Opcional |
payer.token | Body. String | Token de pagamento (payer_token) obtido no fluxo de vinculação, utilizado para cobrar a carteira do comprador. | Obrigatório |
payer.type_token | Body. String | Tipo do token. Para pagamentos via Wallet Connect, o valor deve ser wallet-tokens. | Obrigatório |
capture | Body. Boolean | Indica se o pagamento deve ser capturado imediatamente. Em pagamentos em duas etapas, envie false para reservar o valor e capture-o posteriormente enviando true em uma requisição separada. | Opcional |
binary_mode | Body. Boolean | Quando ativado, o pagamento somente pode ser aprovado ou rejeitado. Caso contrário, o pagamento poderá ficar pendente. | Opcional |
Se a solicitação for bem-sucedida, a resposta retornará o status 201 com o pagamento criado.
json{ "id": 10267812, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ], "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" } }
Dentre os parâmetros retornados, temos os indicados na tabela abaixo.
| Parâmetro | Tipo | Descrição |
id | Number | Identificador único do pagamento criado. Utilize-o para consultar, capturar ou reembolsar o pagamento. |
payments.status | String | Retorna o status do pagamento. Os valores possíveis são approved, in_process e rejected. |
payments.status_detail | String | Detalha o motivo do status do pagamento. Nos pagamentos aprovados, retorna accredited. |
payments.transaction_amount | Number | Valor efetivamente cobrado do comprador. |
payments pode ser rejected dependendo do estado da conta do comprador, mesmo quando a requisição retorna 201. Verifique sempre o status de cada pagamento antes de confirmar a compra ao comprador.A consulta permite obter os dados atualizados de um pagamento realizado pela Advanced Payments API, incluindo o seu status.
Para realizar a consulta, envie uma solicitação ao endpoint /v1/advanced_payments/{advanced_payment_id}GET, incluindo seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o advanced_payment_id obtido na resposta à sua criação.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/advanced_payments/{{ADVANCED_PAYMENT_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Parâmetro | Tipo | Descrição | Obrigatoriedade |
advanced_payment_id | Path. Number | Identificador único do pagamento que se deseja consultar, obtido na resposta à sua criação. | Obrigatório |
Authorization | Header | Refere-se ao Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`.. | Obrigatório |
Se a solicitação for bem-sucedida, a resposta retornará o status 200 com os dados atualizados do pagamento.
json{ "id": 10267812, "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ] }