Skip to main content
POST
Criar transação
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, pix ou boleto → o pagamento é cobrado imediatamente no gateway. Para cartão, os dados vão em creditCard; para Pix e boleto, os objetos pix/boleto são opcionais e servem só para customizar a expiração. No Pix, o QR Code (pixUrl/pixCopyPaste) já vem preenchido na resposta síncrona do POST.
  • Sem nenhum deles → o pagamento nasce registrado e não cobrado, e a transação fica em pending. Você cobra quando quiser, em POST /transactions/:id/payments/process. É o caminho para ter o número do pedido antes de o comprador digitar o cartão.
payments não aceita lista vazia. A transação precisa nascer com pelo menos um pagamento, ainda que sem os dados de cobrança. Não existe rota para acrescentar um pagamento a uma transação já criada — sem nenhum, ela ficaria em pending para sempre, e a única saída seria criar outra. Enviar [] ou omitir o campo resulta em 400.
Endpoint idempotente. Envie o header 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

customer e customerId são mutuamente exclusivos. Envie um dos dois (obrigatório): customerId para reusar um cliente já cadastrado, ou customer inline para criar/identificar o cliente no ato. Enviar os dois, ou nenhum, resulta em 400.
A soma dos pagamentos deve bater com a soma dos itens. Quando payments é enviado, a soma de payment.amount precisa ser exatamente igual ao total dos itens (Σ item.amount × item.quantity). Caso contrário, 400. Todos os valores são inteiros em centavos.
Expiração de Pix e boleto tem default. Sem 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.
O token do cartão muda de nome entre as APIs. O Tokenizer devolve o campo como tokenId; aqui ele entra como creditCard.token, e no Checkout como card.tokenId. É o mesmo valor — só o nome do campo acompanha o contexto.
statementDescriptor é normalizado antes de ir para a fatura. A criação aceita até 100 caracteres, mas o texto persistido e enviado à adquirente passa por três etapas: os acentos são removidos (é → e), tudo que não for letra, número ou espaço cai fora, e o resultado é cortado em 13 caracteres. "Café & Cia" chega ao portador como "Cafe Cia".A limpeza não é preciosismo: a adquirente recusa a cobrança inteira se o descritor trouxer caractere especial. Por isso o campo é saneado em vez de rejeitado — e por isso a resposta já o devolve na forma final. Use um texto curto, sem acento e reconhecível na fatura.
O endereço da compra volta para o cadastro do cliente. Além de virar o 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

O item custa 9990 centavos (R$ 99,90) e o pagamento soma 9990 — as somas batem, então a requisição é válida.
Resposta 201 Created. O exemplo de JSON é ilustrativo — confira os campos reais na resposta do seu ambiente.
O pagamento já volta com 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.
Na resposta, cada item traz 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

Um item com valor unitário de 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

​
x-api-key
string
header
required

API Key da Credential (gerada no Backoffice)

Headers

​
Idempotency-Key
string

Chave única para garantir idempotência da requisição (TTL 7 dias)

Body

application/json
​
referenceCode
string
required

Código de referência do integrador (1–255 chars); sem validação de unicidade — pode repetir entre transações.

Required string length: 1 - 255
​
items
object[]
required

Itens da transação; o total é a soma de amount × quantity de cada item.

Minimum array length: 1
​
payments
object[]
required

Payments da transação (valores em centavos); com dados de processamento processa via gateway, sem eles ficam pendentes; omitido, a transação fica waiting_payment.

Minimum array length: 1
​
customerId
string | null

ID de um cliente existente (mutuamente exclusivo com customer).

​
customer
object

Dados do cliente inline (mutuamente exclusivo com customerId).

​
currency
enum<string>

Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL', que também é o padrão quando o campo é omitido.

Available options:
BRL
​
ip
string | null

IP do comprador (antifraude).

​
ipSource
enum<string> | null

Origem do IP: observed quando lido da conexão do comprador (checkout), declared quando informado pelo integrador. Ausente vira declared.

Available options:
observed,
declared
​
additionalInfo
object

Metadados livres (chave → valor), devolvidos nos webhooks da transação.

Response

Transação criada

​
id
string

Identificador único do registro.

​
customerId
string

ID do cliente associado à transação.

​
amount
integer

Valor em centavos.

​
currency
string

Moeda no padrão ISO 4217 (ex.: BRL).

​
paidAmount
integer

Valor efetivamente pago, em centavos.

​
refundedAmount
integer

Valor total estornado, em centavos.

​
status
string

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.

​
parentTransactionId
any | null

ID da transação de origem, quando esta é derivada de outra.

​
referenceCode
string

Código de referência definido pelo integrador na criação.

​
ip
string

Endereço IP de origem da transação.

​
additionalInfo
object

Informações adicionais do registro (dados livres).

​
customerName
string

Nome do cliente da transação.

​
customerEmail
string

E-mail do cliente da transação.

​
customerDocument
string

Documento (CPF ou CNPJ) do cliente da transação.

​
customerDocumentType
string

Tipo de documento do cliente: cpf ou cnpj.

​
customerPhone
string

Telefone do cliente da transação.

​
createdAt
string<date-time>

Data e hora de criação do registro (ISO 8601).

​
updatedAt
string<date-time>

Data e hora da última atualização do registro (ISO 8601).

​
paidAt
any | null

Data e hora em que o pagamento foi liquidado (ISO 8601).

​
expiresAt
any | null

Data e hora em que o registro expira (ISO 8601).

​
canceledAt
any | null

Data e hora em que a transação foi cancelada (ISO 8601).

​
refundedAt
any | null

Data e hora em que o estorno foi concluído (ISO 8601).

​
chargedbackAt
any | null

Data e hora em que a transação sofreu chargeback (ISO 8601).

​
protestedAt
any | null

Data e hora em que a transação foi protestada (ISO 8601).

​
items
object[]

Itens da transação. Vazio quando a transação não tem itens.

​
payments
object[]

Pagamentos da transação, com cartão e splits quando houver.

​
customer
object | null

Cliente da transação, quando customerId está preenchido. Não vem na listagem — use GET /customers/{id}.

​
customerAddress
object | null

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.