Skip to main content
POST
Criar Pedido
Este endpoint permite criar pedidos e processar pagamentos usando diferentes métodos (cartão, PIX, boleto, Google Pay), com suporte completo a parcelamento, split de pagamento, 3D Secure e Network Tokens.

Idempotência (obrigatória)

Esta rota exige o header Idempotency-Key — uma chave única que você gera por cobrança (ex.: um UUID). Sem ele, a resposta é 400.
Como o middleware trata a chave (reserve-before):
  • Repetição segura (replay): a mesma chave com o mesmo corpo devolve a resposta original, sem criar uma segunda cobrança — ideal para retry após timeout de rede.
  • Conflito (409): a mesma chave com um corpo diferente é rejeitada.
  • Em voo: se a primeira requisição com aquela chave ainda está processando, a segunda recebe 409 com o header Retry-After (segundos para tentar de novo).
Gere uma chave por intenção de cobrança, não por request: se o cliente clicou “pagar” uma vez, use a mesma Idempotency-Key em todos os retries daquela cobrança.

Parâmetros Obrigatórios

string
required
Descrição do pedidoMáximo: 255 caracteres
string
required
Referência única para este pedido no sistema do comercianteExemplo: ORDER-2024-001 | Máximo: 255 caracteres
string
required
Merchant Category Code (código de categoria do estabelecimento)Formato: 4 dígitos | Exemplo: 5411 (supermercado)

Parâmetros Opcionais

string
URL para receber notificações de mudança de status (webhook)Exemplo: https://seusite.com/webhook/autorizou

Dados do Cliente

object
required

Dados do Pagamento

object
required

Pagamento com Cartão de Crédito

object
Obrigatório quando: payment_method = "credit_card"

Pagamento PIX

object
Obrigatório quando: payment_method = "pix"

Pagamento com Boleto

object
Obrigatório quando: payment_method = "bank_slip"

Pagamento com Google Pay

object
Obrigatório quando: payment_method = "google_pay"

Pagamento com Apple Pay

object
Obrigatório quando: payment_method = "apple_pay"
Novo! Apple Pay agora está disponível. Veja o guia completo de integração para começar.

Split de Pagamento

array
Divisão do pagamento entre múltiplos destinatários
Importante sobre validação do Split:
  • Cada split individual não pode ser maior que payment.amount
  • A soma de todos os splits não pode ultrapassar payment.amount
  • A soma pode ser menor que o total (a diferença fica com o merchant principal)

3D Secure (3DS)

object
Dados para autenticação 3D Secure (recomendado para maior segurança)
3D Secure 2.0: Melhora significativamente a taxa de aprovação e reduz fraudes. Altamente recomendado para pagamentos de alto valor.

Itens do Pedido

array
Lista de itens/produtos do pedido (opcional mas recomendado)

Estrutura da Resposta

A resposta contém informações completas sobre o pedido e pagamento criados:

Campos do Pedido (Order)

Campos do Pagamento (Payment)

Campos Específicos de Cartão (quando payment_method = credit_card)

Campos Específicos de Apple Pay (quando payment_method = apple_pay)

Campos de Taxas (Fee)

Objeto 3DS (three_ds): Quando a autenticação 3D Secure é realizada, este objeto conterá informações sobre o resultado da autenticação, incluindo authentication_url caso seja necessário redirecionar o cliente.

Exemplos de Requisição

Pagamento com Cartão

Requisição

Resposta

Autenticação 3D Secure: quando o emissor exige o desafio, o pagamento volta com payment.status: "authentication_requested" e o objeto payment.metadata traz os dados do desafio para você conduzir a autenticação. Concluído o desafio, o status segue o fluxo normal (authorized/refused). Veja a seção 3D Secure (3DS) para mais detalhes.
Venda com divisão: quando a venda é dividida (você enviou split[] ou a conta tem split por configuração), a resposta traz também o bloco split com a divisão realizada — veja Split de Pagamento.

Pagamento PIX

Requisição

Resposta

O conteúdo copia-e-cola do PIX é o próprio payment.pix.qr_code (payload EMV). Para exibir a imagem, gere o QR a partir dele na sua aplicação. O pagamento confirma de forma assíncrona: aguarde o webhook payment.authorized ou consulte GET /payments/{id}.

Pagamento Apple Pay

Requisição

Resposta

Integração Apple Pay: Para implementar o Apple Pay em seu frontend e obter o apple_pay_token, consulte o Guia Completo de Integração Apple Pay.
Salvamento Automático: A Autorizou salva automaticamente a carteira digital após o primeiro pagamento bem-sucedido com Apple Pay. O apple_pay.id retornado na resposta pode ser usado como digital_wallet_uuid em cobranças futuras, eliminando a necessidade de solicitar o token Apple Pay novamente.

Venda com Split

Requisição

Resposta

No bloco split da resposta, recipient: null indica a fatia que fica com a sua própria conta. Os itens ecoam a divisão realizada (enviada no split[] ou resolvida pela configuração da conta).

Códigos de Erro

Recusa de pagamento NÃO é erro HTTP. Quando a cobrança é processada e o emissor recusa, a resposta é 201 Created com payment.status: "refused", o motivo em payment.refused_reason e o código do emissor em payment.return_code. Trate recusa lendo o corpo, não o status HTTP.
Falta o header obrigatório Idempotency-Key (veja a seção de idempotência no topo).
Chave de API ausente ou inválida no header Authorization: Bearer.
A mesma Idempotency-Key foi reutilizada com um corpo diferente, ou a requisição original com essa chave ainda está em processamento (neste caso a resposta traz o header Retry-After com os segundos para tentar de novo).
Validação dos dados falhou. O corpo segue o formato padrão de validação:
Possíveis causas: parâmetros obrigatórios faltando, tipos incorretos, valores fora dos limites, soma do split[] incompatível com o valor da venda.

Regras de Negócio

Valores e Limites

  • Mínimo: R$ 1,00 (100 centavos)
  • Máximo: Conforme limite do merchant
  • Parcelamento: Até 12x para cartão de crédito
  • Taxa: Calculada automaticamente conforme tabela do merchant
  • Cartão: Captura imediata ou até 5 dias
  • PIX: Expiração configurável (até 24h)
  • Boleto: Vencimento configurável
  • 3DS: Autenticação deve ser concluída em 15 minutos
  • Cartão deve estar ativo e não expirado
  • Split deve somar exatamente o valor total
  • Cliente deve ter cadastro válido
  • MCC deve estar autorizado para o merchant

Split de Pagamentos

Como Funciona

O Split permite dividir o valor de um pagamento entre múltiplos destinatários. Ideal para marketplaces, plataformas multi-vendor e agregadores.

Regras de Split

  1. Soma dos valores deve ser igual a payment.amount
  2. Recebedors devem estar previamente cadastrados
  3. Taxas podem ser atribuídas a destinatários específicos
  4. Responsabilidade por chargebacks pode ser configurada

Tipos de Split

Valor fixo em centavos destinado ao recipiente
Percentual do valor total
Nota: Mesmo com type = "percentage", o campo amount deve conter o valor já calculado em centavos.

Configuração de Taxas

Define se o destinatário paga a taxa de processamentoExemplo: Taxa de 3% = R30,00emumavendadeR 30,00 em uma venda de R 1.000,00
  • true: Recebedor recebe R$ 970,00 (desconta a taxa)
  • false: Recebedor recebe R$ 1.000,00 (marketplace paga)
Define se o destinatário paga taxas de ajuste/restoTaxas residuais de arredondamento ou divisões não exatas
Define responsabilidade por chargebacks
  • true: Recebedor é responsável e terá valores descontados em caso de chargeback
  • false: Marketplace/Plataforma assume o risco

Exemplo Prático de Split

3D Secure (3DS)

3D Secure é um protocolo de autenticação adicional que aumenta a segurança e taxa de aprovação.

Quando Usar

  • Pagamentos de alto valor (acima de R$ 500)
  • Primeiro uso do cartão
  • Cliente internacional
  • Comportamento suspeito detectado

Implementação Básica

Para usar 3DS, envie o parâmetro authentication_data com informações do navegador:

Próximos Passos

Após criar um pedido:
  1. Configurar webhooks para notificações em tempo real
  2. Consultar detalhes do pagamento
  3. Processar estornos quando necessário
  4. Consultar recebedores do split