Criar transação
Cria uma transação com seus itens e pagamentos, cobrando na mesma requisição ou deixando a cobrança para depois.
POST /transactions
Faz parte do recurso Transações — o conceito, o ciclo de vida e a
tabela de status estão lá.
Cria uma transação. São obrigatórios o cliente, o seu código de referência
(referenceCode), pelo menos um item e pelo menos um pagamento. O que decide se a cobrança
acontece agora ou depois não é a presença do payments, e sim a dos dados do meio de pagamento
dentro dele:
- Com
creditCard,pixouboleto→ o pagamento é cobrado imediatamente no gateway. Para cartão, os dados vão emcreditCard; para Pix e boleto, os objetospix/boletosão opcionais e servem só para customizar a expiração. No Pix, o QR Code (pixUrl/pixCopyPaste) já vem preenchido na resposta síncrona doPOST. - Sem nenhum deles → o pagamento nasce registrado e não cobrado, e a transação fica em
pending. Você cobra quando quiser, emPOST /transactions/:id/payments/process. É o caminho para ter o número do pedido antes de o comprador digitar o cartão.
Idempotency-Key (TTL de 7 dias) para garantir que reenvios
da mesma requisição não criem transações duplicadas. Veja Convenções.Regras de negócio importantes
pix.expirationDate, o QR Code vale 30
minutos; sem boleto.expirationDate, o boleto vence em 3 dias. Os dois objetos existem
só para mudar isso — o pagamento é processado com ou sem eles.tokenId; aqui ele entra como creditCard.token, e no Checkout como card.tokenId. É o
mesmo valor — só o nome do campo acompanha o contexto.customerAddress
congelado na transação, o customer.address informado aqui atualiza o cadastro — campo a
campo: valor preenchido substitui, valor vazio não apaga o que já estava lá. Um checkout que
pede só o CEP não zera rua, cidade e estado de quem já tinha endereço.A atualização é best-effort: se falhar, a venda segue normalmente, porque a transação já guarda o
seu próprio snapshot.Exemplo: criar transação com Pix
9990 centavos (R$ 99,90) e o pagamento soma 9990 — as somas batem, então a
requisição é válida.201 Created. O exemplo de JSON é ilustrativo — confira os campos reais na resposta do seu ambiente.pixUrl (URL da imagem do QR Code) e pixCopyPaste (BR Code
copia-e-cola, EMV iniciando em 00020126...) preenchidos na própria resposta síncrona do create —
é esse o dado que você exibe ao comprador. O status waiting_payment significa que o QR Code foi
emitido e aguarda o pagador; expiresAt reflete a expiração default de 30 minutos.unitValue (o valor unitário que você enviou em items[].amount)
e amount (o total da linha = unitValue × quantity). Com quantity: 1 os dois coincidem;
no exemplo de cartão abaixo, com quantity: 2, o amount é o dobro do unitValue.Exemplo: criar e cobrar cartão com cartão tokenizado
5000 centavos (R$ 50,00) e quantity: 2 → total de 10000
centavos (R$ 100,00); o pagamento soma 10000. As somas batem. O cartão é
enviado como token (gerado pelo Tokenizer) — nunca envie dados crus
do cartão para a API.Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição (TTL 7 dias)
Body
Código de referência do integrador (1–255 chars); sem validação de unicidade — pode repetir entre transações.
1 - 255Itens da transação; o total é a soma de amount × quantity de cada item.
1Payments da transação (valores em centavos); com dados de processamento processa via gateway, sem eles ficam pendentes; omitido, a transação fica waiting_payment.
1ID de um cliente existente (mutuamente exclusivo com customer).
Dados do cliente inline (mutuamente exclusivo com customerId).
Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL', que também é o padrão quando o campo é omitido.
BRL IP do comprador (antifraude).
Origem do IP: observed quando lido da conexão do comprador (checkout), declared quando informado pelo integrador. Ausente vira declared.
observed, declared Metadados livres (chave → valor), devolvidos nos webhooks da transação.
Response
Transação criada
Identificador único do registro.
ID do cliente associado à transação.
Valor em centavos.
Moeda no padrão ISO 4217 (ex.: BRL).
Valor efetivamente pago, em centavos.
Valor total estornado, em centavos.
Situação da transação, derivada dos pagamentos. Valores: pending, waiting_payment, partially_paid, paid, refused, failed, canceled, waiting_refund, partially_refunded, refunded, chargeback, in_protest.
ID da transação de origem, quando esta é derivada de outra.
Código de referência definido pelo integrador na criação.
Endereço IP de origem da transação.
Informações adicionais do registro (dados livres).
Nome do cliente da transação.
E-mail do cliente da transação.
Documento (CPF ou CNPJ) do cliente da transação.
Tipo de documento do cliente: cpf ou cnpj.
Telefone do cliente da transação.
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).
Data e hora em que o pagamento foi liquidado (ISO 8601).
Data e hora em que o registro expira (ISO 8601).
Data e hora em que a transação foi cancelada (ISO 8601).
Data e hora em que o estorno foi concluído (ISO 8601).
Data e hora em que a transação sofreu chargeback (ISO 8601).
Data e hora em que a transação foi protestada (ISO 8601).
Itens da transação. Vazio quando a transação não tem itens.
Pagamentos da transação, com cartão e splits quando houver.
Cliente da transação, quando customerId está preenchido. Não vem na listagem — use GET /customers/{id}.
Endereço informado nesta compra, congelado no momento da criação. É este que vale para nota fiscal e antifraude: editar o cadastro do cliente depois não o altera. Compare com customer.address, que reflete o cadastro atual.