Este endpoint permite criar uma order no modo automatic (processando a transação em uma única etapa) ou manual (processando a transação em etapas que podem ser configuradas e executadas de forma incremental) para transações de pagamento com Checkout Transparente. Em caso de sucesso, a requisição retornará uma resposta com o status 201.
POST
OBRIGATÓRIO
OBRIGATÓRIO
online.OBRIGATÓRIO CONDICIONAL
automatic e opcional no modo manual. Caso não seja enviado no modo manual, oonline.manual, enquanto configura o processamento para ser feito posteriormente, utilizando o endpoint POST /v1/orders/{order_id}/process.automatic.Erros
Cada resposta da API inclui um código de status HTTP com o resultado da requisição. O código 200 indica sucesso, o 400 um erro nos dados enviados e o 500 uma falha interna no servidor.
Alguns erros 400 podem ser tratados de forma programática e incluem um código que descreve a causa do erro.
400Erro de requisição.
empty_required_header
O header X-Idempotency-Key é requerido e não foi enviado. Faça a requisição novamente incluindo-o.
invalid_idempotency_key_length
O valor enviado no header X-Idempotency-Key excedeu o tamanho máximo permitido. O header aceita valores entre 1 e 128 caracteres.
required_properties
Algumas propriedades obrigatórias estão ausentes. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
unsupported_properties
Foi enviada uma propriedade que não é suportada. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
minimum_properties
O número mínimo de propriedades necessárias para executar a solicitação não foi enviado. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
property_type
Um tipo de propriedade incorreto foi enviado. Por exemplo, um valor integer para uma propriedade string. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
minimum_items
O número mínimo de itens para alguma propriedade não foi enviado. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
maximum_items
Foi enviado um número de itens maior do que o permitido para alguma propriedade. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
property_value
Um valor inválido foi enviado para alguma propriedade. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente. Esse erro também é retornado quando o domínio ou o conteúdo de payer.email não é permitido.
json_syntax_error
Um JSON inválido foi enviado. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
invalid_properties
Informações incorretas foram enviadas. Verifique a mensagem retornada nos detalhes do erro para identificar o problema e tente novamente.
invalid_total_amount
O valor informado em total_amount não equivale à soma do campo transactions.payments.amount do total de transações. Verifique se os valores estão corretos.
invalid_email_for_sandbox
O formato do email é inválido para o ambiente de sandbox, deve conter @testuser.com.
order_invalid_sponsor_id
O identificador do patrocinador da order (sponsor.id) é inválido. Certifique-se de que o ID está correto.
invalid_header_value
Identificador do chamador (caller_id) não encontrado. Certifique-se de que o ID está correto.
order_builder_without_transactions
O nó transactions da order criada em modo manual não pode ser um array vazio. Envie-o com o valor null para tentar novamente.
invalid_order_type
O tipo de order fornecido é inválido ou não é suportado. Esperado um de: online.
401Erro. Access Token não autorizado.
401
O Access Token enviado está incorreto. Revise o valor e tente enviar a requisição novamente com a informação correta.
invalid_credentials
Não há suporte para credenciais de teste. Utilize usuários de teste com credenciais de produção para o ambiente de teste ("sandbox") e as suas credenciais de produção para o ambiente de produção.
402Erro de processamento.
402
A order foi criada mas alguma transação falhou. Verifique o campo errors para mais informações.
403Erro. Proibido.
forbidden
A aplicação não tem permissão para acessar este recurso. Verifique se o Access Token utilizado tem as permissões e escopos necessários para esta operação.
PA_UNAUTHORIZED_RESULT_FROM_POLICIES
A conta está bloqueada e suas chaves de API foram revogadas. Ao menos uma política avaliada pelo Policy Agent retornou um resultado não autorizado (UNAUTHORIZED).
409Alguma regra específica do sistema não permite a realização da ação devido a restrições definidas.
idempotency_key_already_used
O valor enviado como header de idempotência (X-Idempotency-Key) já foi utilizado. Por favor, tente a solicitação novamente enviando um novo valor.
423Recurso bloqueado.
resource_locked
Chave de idempotência (X-Idempotency-Key) bloqueada. Por favor, tente novamente após algum tempo.
429Limite de requisições excedido.
too_many_requests
Client ID bloqueado pelo gateway porque o limite de requisições pelo ID em questão foi atingido. Leia o header Retry-After da resposta e aguarde o número de segundos indicado antes de tentar novamente. Para maior resiliência, implemente backoff exponencial com jitter, ou seja, aumente o tempo de espera a cada nova tentativa e adicione uma variação aleatória para evitar o reenvio simultâneo de muitas requisições.
usage_quota_exceeded
Cota imposta pelo backend da API porque o limite de requisições por cliente foi atingido. Leia o header Retry-After da resposta e aguarde o número de segundos indicado antes de tentar novamente. Para maior resiliência, implemente backoff exponencial com jitter, ou seja, aumente o tempo de espera a cada nova tentativa e adicione uma variação aleatória para evitar o reenvio simultâneo de muitas requisições.
500Erro genérico.
idempotency_validation_failed
Falha na validação de idempotência. Tente enviar a solicitação novamente.
internal_error
Erro genérico. Tente enviar a solicitação novamente.
curl -X POST \
'https://api.mercadopago.com/v1/orders'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-8*********88776-122*********fc20dede6*********a497d7225*********64' \
-H 'X-Idempotency-Key: 3fdaeae8-e19b-43de-acb2-bd498674e9a5' \
-d '{
"type": "online",
"external_reference": "ext_ref_1234",
"transactions": {
"payments": [
{
"amount": "24.50",
"payment_method": {
"id": "visa",
"type": "credit_card",
"token": "12345",
"installments": 1,
"statement_descriptor": "My Store"
},
"expiration_time": "P3Y6M4DT12H30M5S",
"date_of_expiration": "2027-12-31T10:00:00.000-04:00"
}
]
},
"payer": {
"email": "test@testuser.com",
"entity_type": "individual",
"first_name": "João",
"last_name": "Silva",
"identification": {
"type": "CPF",
"number": "19119119100"
},
"phone": {
"area_code": "11",
"number": "98765-4321"
},
"address": {
"zip_code": "06233-903",
"street_name": "Rua Teste",
"street_number": "3003",
"neighborhood": "Bonfim",
"state": "SP",
"city": "Osasco",
"complement": "Apto 303"
}
},
"shipment": {
"address": {
"zip_code": "06233-903",
"street_name": "Rua Teste",
"street_number": "3003",
"neighborhood": "Bonfim",
"city": "Osasco",
"state": "SP",
"complement": "Apto 303"
}
},
"total_amount": "50.00",
"capture_mode": "automatic",
"processing_mode": "automatic",
"description": "Smartphone",
"integration_data": {
"integrator_id": "dev_123",
"platform_id": "1234567890",
"sponsor": {
"id": "<YOUR_SPONSOR_ID>"
}
},
"items": [
{
"title": "Smartphone",
"unit_price": "24.50",
"quantity": 1,
"description": "Smartphone",
"external_code": "1234",
"picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
"category_id": "MLB1055",
"type": "MLB1055",
"warranty": true,
"event_date": "2014-06-28T16:53:03.176-04:00"
}
],
"config": {
"online": {
"transaction_security": {
"validation": "on_fraud_risk",
"liability_shift": "required"
}
}
}
}'{
"id": "ORD01J49MMW3SSBK5PSV3DFR32959",
"type": "online",
"processing_mode": "automatic",
"external_reference": "ext_ref_1234",
"total_amount": "50.00",
"total_paid_amount": "50.00",
"integration_data": {
"application_id": "1234",
"integrator_id": "dev_123",
"platform_id": "1234567890",
"sponsor": {
"id": "<YOUR_SPONSOR_ID>"
}
},
"created_date": "2024-08-26T13:06:51.045317772Z",
"last_updated_date": "2024-08-26T13:06:51.045317772Z",
"country_code": "BR",
"status": "processed",
"status_detail": "accredited",
"capture_mode": "automatic",
"shipment": {
"address": {
"zip_code": "06233-903",
"street_name": "Rua Teste",
"street_number": "3003",
"neighborhood": "Bonfim",
"city": "Osasco",
"state": "SP",
"complement": "Apto 303"
}
},
"transactions": {
"payments": [
{
"id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
"amount": "50.00",
"paid_amount": "47.28",
"taxes_amount": "0.50",
"reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
"status": "processed",
"status_detail": "accredited",
"expiration_time": "P3Y6M4DT12H30M5S",
"payment_method": {
"id": "visa",
"type": "credit_card",
"token": "12345",
"installments": 1,
"installment_amount": "8.30",
"statement_descriptor": "My Store",
"ticket_url": "https://www.mercadopago.com.br/sandbox/payments/0101010101010/ticket?caller_id=01010101010&payment_method_id=bolbradesco&payment_id={ID}&payment_method_reference_id=010101010&hash=9f68bbab-e685-47d2-9dc8-b9be2d84167f",
"barcode_content": "3335008800000000006004835002100020000242462010",
"reference": "6005407530",
"verification_code": "6005407530",
"financial_institution": "bradesco",
"digitable_line": "23793380296060054351030006333303799140000020000",
"qr_code": "00020126580014br.gov.bcb.pix0136b76aa9c2-2ec4-4110-954e-ebfe34f05b61520400005303986540510.005802BR5912TESTPVBWOSBE6009Sao Paulo62240520mpqrinter715936942186304C3C0",
"qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAABWQAAAVkAQAAAAB79i",
"e2e_id": "PIXE18236120202509281610s04cf5a1234",
"transaction_security": {
"validation": "on_fraud_risk",
"liability_shift": "required",
"url": "https://www.mercadopago.com/auth/card/validation/pages/remedies/019ada0a-fe1f-7a82-ba1a-1ccb4e0232e7?display_mode=self_hosted&guest_token=0661345a-e0e1-4c09-aff9-b7929ca9a24a",
"id": "019ada0a-fe1f-7a82-ba1a-1ccb4e0232e7",
"type": "three_ds",
"status": "AUTHENTICATED"
}
},
"date_of_expiration": "2027-12-31T10:00:00.000-04:00"
}
]
},
"description": "Smartphone",
"items": [
{
"title": "Smartphone",
"unit_price": "24.50",
"quantity": 1,
"description": "Smartphone",
"external_code": "1234",
"picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
"category_id": "MLB1055",
"type": "MLB1055",
"warranty": "true",
"event_date": "2014-06-28T16:53:03.176-04:00"
}
],
"client_token": "QWERTY12345.ASDFG67890",
"config": {
"online": {}
}
}