Skip to main content
POST
Crie uma nova transação (venda) na plataforma. Você pode processar pagamentos via PIX, Cartão de Crédito, Cartão de Débito ou Boleto.

​
Autenticação

Este endpoint requer autenticação via API Keys:
​
string
required
Sua chave pública da API
​
string
required
Sua chave privada da API

​
Parâmetros do Body

​
integer
required
Valor da transação em centavos (ex: 10000 = R$ 100,00)
​
string
required
Método de pagamento. Valores possíveis: CREDIT_CARD, DEBIT_CARD, BOLETO, PIX, PIX_AUTOMATICO, TRANSFER
​
object
required
Dados do cliente
​
string
required
Nome completo do cliente
​
string
required
Email do cliente
​
object
Documento do cliente (CPF ou CNPJ)
​
string
Tipo do documento: cpf ou cnpj
​
string
Número do documento
​
string
Telefone do cliente no formato 11999999999 (sem caracteres especiais)
​
object
Configuração da recorrência (obrigatório para PIX_AUTOMATICO ao criar uma autorização nova). Para cobrar um ciclo de uma autorização que já existe, envie metadata.idRec em vez deste bloco.
​
string
required
Identificador da autorização no seu sistema — é o que o cliente enxerga no app do banco e o que você usa para reconciliar. Máximo de 35 caracteres (limite do protocolo; acima disso a transação é recusada).
​
string
required
Data estimada do primeiro pagamento, no formato YYYY-MM-DD.
​
string
default:"MENSAL"
Intervalo entre as cobranças: SEMANAL, MENSAL, TRIMESTRAL, SEMESTRAL ou ANUAL.
​
integer
default:"3"
Como o cliente autoriza a recorrência:
  • 1 — notificação push, sem QR. Para migrar assinantes que já existem.
  • 2 — QR de recorrência futura: autoriza agora, primeira cobrança depois.
  • 3 — QR composto: paga o primeiro ciclo e autoriza os próximos numa única leitura. É o padrão, e o que o checkout usa.
  • 4 — QR composto com cobrança com vencimento.
​
string
default:"PERMITE_3R_7D"
O que fazer quando um débito falha: PERMITE_3R_7D (até 3 tentativas em 7 dias) ou NAO_PERMITE.
​
string
Encerra a recorrência nesta data (YYYY-MM-DD). Omita para autorização por tempo indeterminado.
​
string
Texto que ajuda o cliente a reconhecer a cobrança no app do banco. Máximo de 35 caracteres — valores maiores são truncados.
​
object
Dados bancários do cliente. Obrigatório apenas na jornada 1, que autoriza por push e precisa saber para qual conta enviar a notificação. Campos: agencia, conta, cpf e ispbParticipante.
A jornada muda o formato da resposta.Nas jornadas 3 e 4, a autorização já cobra o primeiro ciclo — a resposta é uma venda normal, com sale preenchido.Nas jornadas 1 e 2, nada é cobrado no momento da autorização. A resposta vem com sale: null e apenas os dados da recorrência, porque criar uma venda ali duplicaria o primeiro ciclo quando ele fosse cobrado de verdade. A cobrança acontece a partir de dataInicial, e você recebe o webhook quando ela ocorrer.
O qrCode é o código copia-e-cola que o cliente usa para autorizar. Nas jornadas 3 e 4 ele é composto: a mesma leitura paga a primeira parcela e autoriza as seguintes. Guarde o idRec — é com ele que você cobra os próximos ciclos e cancela a recorrência.
​
object
Informações do cartão (obrigatório para CREDIT_CARD ou DEBIT_CARD)
​
string
Número do cartão (será tokenizado - apenas últimos 4 dígitos são armazenados)
​
string
Nome do portador do cartão (será tokenizado)
​
string
Mês de expiração no formato MM
​
string
Ano de expiração no formato YYYY
​
string
CVV do cartão (não é armazenado conforme PCI DSS)
​
integer
Número de parcelas (apenas para cartão de crédito)
​
object
Informações do PIX (obrigatório para PIX)
​
string
Chave PIX do recebedor
​
integer
Número de dias para expiração do PIX
​
object
Informações do boleto (obrigatório para BOLETO)
​
integer
Número de dias para expiração do boleto
​
array
required
Lista de itens da transação
​
string
required
Nome do produto
​
integer
required
Preço unitário em centavos
​
integer
required
Quantidade do item
​
boolean
required
Se o item é físico (true) ou digital (false)
​
integer
ID do produto (opcional)
​
string
ID do plano (opcional)
​
string
Nome do plano (opcional)
​
string
ID customizado do item (opcional)
​
object
Informações de entrega (obrigatório quando há itens físicos com tangible: true)
​
string
Rua
​
string
Número
​
string
Complemento
​
string
CEP
​
string
Bairro
​
string
Cidade
​
string
Estado (2 dígitos em maiúscula, ex: SP)
​
string
País (2 dígitos, ex: br)
​
object
Configuração de parcelas (apenas para cartão de crédito)
​
integer
Número de parcelas (1 a 12)
​
string
URL para receber notificações de mudança de status da venda
​
string
Origem da campanha (UTM Source). Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Meio da campanha (UTM Medium). Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Nome da campanha (UTM Campaign). Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Conteúdo da campanha (UTM Content). Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Termo da campanha (UTM Term). Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Fonte personalizada. Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
string
Código de campanha personalizado. Funciona para qualquer método de pagamento (PIX, cartão, boleto, etc.)
​
object
Dados adicionais da venda (objeto JSON livre)
A resposta traz sale.uuid, o identificador público da venda (UUID). Guarde e use o uuid para consultar a venda em Buscar Transação e para casar os webhooks. O sale.id numérico continua presente para integrações antigas.

​
Códigos de Erro

​
Status HTTP