Criar uma transação

Este endpoint cria uma nova transação de pagamento. Os métodos suportados na criação são cartão de crédito (credit), PIX (pix) e boleto (billet), com configurações flexíveis como captura automática ou

Visão Geral

Este endpoint cria uma nova transação de pagamento. Os métodos suportados na criação são cartão de crédito (credit), PIX (pix) e boleto (billet), com configurações flexíveis como captura automática ou manual, parcelamento, financiamento automático de juros, cupons empilháveis, split de marketplace, cobrança em nome de uma sub-conta (onBehalfOf), multa/juros/desconto no boleto e PIX com vencimento (cobv).

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

Métodos de Pagamento: na criação só são aceitos credit, pix e billet. Forneça todos os dados obrigatórios para o método escolhido (cartão para crédito; endereço de cobrança para boleto).
Dados Sensíveis: informações de cartão de crédito devem ser transmitidas com segurança. Recomenda-se sempre usar cartões tokenizados (payment.card.id) em vez de enviar os dados completos do cartão.
CVV não é persistido: o código de segurança é usado apenas na autorização e nunca é armazenado.
Webhooks: configure webhooks para receber as mudanças de status da transação — não faça polling.
Idempotência: utilize o header X-Idempotency-Key para evitar criação de transações duplicadas.

Idempotência

Para garantir que uma operação não seja executada mais de uma vez, utilize o header X-Idempotency-Key.

Header	Tipo	Obrigatório	Descrição
`X-Idempotency-Key`	string	Recomendado	Chave única para garantir idempotência da requisição. Recomendamos a utilização de UUIDs v4.

Ao incluir este header, você evita a criação de transações duplicadas caso ocorram problemas de comunicação ou timeouts. Se a mesma chave for enviada novamente dentro da janela de idempotência, o servidor retornará a resposta original da primeira requisição bem-sucedida, sem criar uma nova transação.

Comportamento:

Duas requisições idênticas com a mesma chave: apenas a primeira é processada; a segunda devolve a mesma resposta.
Se a primeira tentativa falhou com erro 5xx, uma nova tentativa com a mesma chave processa a transação.
Mesma chave com corpo diferente retorna erro 422 (Unprocessable Entity).

Definição do Valor da Transação

O campo amount (em centavos) é sempre obrigatório. Ele é o valor antes de descontos (originalAmount na resposta). Limites: mínimo 500 (R$ 5,00) e máximo 20.000.000 (R$ 200.000,00).

Opcionalmente, você pode enviar uma lista de items. Quando items é informado, a soma de unitPrice × quantity de todos os itens deve ser exatamente igual a amount — caso contrário a requisição é rejeitada com 422. Os items são uma itemização do carrinho; eles não substituem o amount.

Requisição

POST /v1/transactions

Exemplos de Requisição por Método de Pagamento

Cartão de Crédito com ID de Cartão

{
  "amount": 10000,
  "payment": {
    "method": "credit",
    "currency": "BRL",
    "capture": true,
    "installments": 3,
    "card": { "id": "card_1234567890" }
  },
  "customer": { "id": "cus_123456789" }
}

Cartão de Crédito com Dados Completos (cliente inline + carrinho)

O cliente pode ser enviado inline (sem id) — firstName, lastName e email são obrigatórios nesse caso; o cliente é localizado ou criado automaticamente antes da cobrança.

{
  "amount": 15000,
  "items": [
    { "name": "Produto Premium", "description": "Produto de alta qualidade", "unitPrice": 10000, "quantity": 1 },
    { "name": "Produto Medium", "description": "Produto de baixa qualidade", "unitPrice": 1000, "quantity": 5 }
  ],
  "payment": {
    "method": "credit",
    "currency": "BRL",
    "installments": 2,
    "card": {
      "holderName": "JOAO SILVA",
      "numbering": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2027",
      "securityCode": "123"
    }
  },
  "customer": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "12345678900" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "987654321" }
  }
}

Boleto Bancário

Para boleto, o endereço do pagador é obrigatório e vai em billing.address (não em customer). Informe um id de endereço salvo ou os campos inline postcode + street + number.

{
  "amount": 18900,
  "payment": {
    "method": "billet",
    "currency": "BRL",
    "billet": {
      "expiresInDays": 3
    }
  },
  "customer": {
    "firstName": "Maria",
    "lastName": "Souza",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "98765432100" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "912345678" }
  },
  "billing": {
    "address": {
      "postcode": "01304-000",
      "street": "Rua Augusta",
      "number": "500",
      "district": "Consolação",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  }
}

PIX

{
  "amount": 5000,
  "payment": {
    "method": "pix",
    "currency": "BRL",
    "pix": { "expiresInMinutes": 30 }
  },
  "customer": {
    "firstName": "Carlos",
    "lastName": "Ferreira",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "45678912300" }
  }
}

Boleto com multa, juros e descontos (billingInstructions)

O boleto aceita termos avançados em payment.billet.billingInstructions: multa por atraso (lateFee), juros (interest) e descontos por antecipação (discounts[]). Todos os offsets de data são relativos ao vencimento (não datas absolutas): startDays = dias após o vencimento; daysBeforeDue = dias antes. Valores em centavos; percentuais de 0 a 100.

{
  "amount": 18900,
  "payment": {
    "method": "billet",
    "billet": {
      "expiresInDays": 5,
      "billingInstructions": {
        "lateFee":  { "mode": "percentage", "percentage": 2, "startDays": 1 },
        "interest": { "mode": "monthlyPercentage", "percentage": 1 },
        "discounts": [
          { "mode": "percentage", "percentage": 10, "daysBeforeDue": 3 }
        ]
      }
    }
  },
  "customer": { "id": "cus_123456789" },
  "billing": { "address": { "id": "addr_123456789" } }
}

Se billingInstructions for omitido, a cobrança herda o default configurado na conta (definido nas configurações da empresa). Enviar o objeto na transação sobrescreve o default para aquela cobrança.

PIX com vencimento (cobv) — PIX datado com desconto

Enviar payment.pix.expiresInDays (em vez de expiresInMinutes) cria um PIX com vencimento (cobv): um PIX datado, como um boleto, que aceita somente discounts em billingInstructions. Exige um customer com nome + documento (CPF/CNPJ).

{
  "amount": 49900,
  "payment": {
    "method": "pix",
    "pix": {
      "expiresInDays": 5,
      "billingInstructions": {
        "discounts": [
          { "mode": "percentage", "percentage": 10, "daysBeforeDue": 3 }
        ]
      }
    }
  },
  "customer": {
    "firstName": "Carlos", "lastName": "Ferreira", "email": "[email protected]",
    "document": { "type": "cpf", "number": "45678912300" }
  }
}

PIX não aplica multa/juros — enviar lateFee/interest em pix.billingInstructions retorna 422. Para multa/juros, use boleto. O PIX cobv é processado via Banco Inter.

Com Cupons (Descontos Empilhados)

Aplique um ou mais cupons via o array discounts[]. Cada item é uma referência ao código de um cupom do catálogo: { "code": "SUMMER10" }. Os cupons empilham e compõem sequencialmente — a ordem importa, pois cada cupom desconta sobre o saldo que restou do anterior. O valor do desconto nunca é lido da requisição: ele é sempre resolvido a partir do cupom no catálogo (validade, limites de uso, escopo). Máximo de 20 cupons.

{
  "amount": 10000,
  "payment": { "method": "pix", "currency": "BRL" },
  "discounts": [
    { "code": "SUMMER10" },
    { "code": "WELCOME" }
  ],
  "customer": { "id": "cus_123456789" }
}

Os campos legados discount (objeto único) e coupon foram removidos — uma cobrança não pode mais carregar um desconto ad-hoc enviado na requisição. Use discounts[] com códigos do catálogo. Cupons inválidos (expirados, esgotados, fora de escopo) ou que deixem o valor abaixo do mínimo retornam HTTP 422 com error.code específico (ex.: couponExpired, couponUsageLimitReached, couponExceedsTotal, discountExceedsAmount).

Cobrança em nome de uma sub-conta (marketplace)

Plataformas de marketplace podem cobrar diretamente em nome de uma sub-conta que possuem, informando onBehalfOf com o publicId da sub-conta. A cobrança passa a ser feita na sub-conta (ela vira o merchant de registro — recebível, saldo e antifraude próprios) e a plataforma recolhe sua taxa de aplicação configurada como um split adicional. Veja Splits.

{
  "amount": 10000,
  "payment": { "method": "pix", "currency": "BRL" },
  "customer": { "id": "cus_123456789" },
  "onBehalfOf": "bus_subseller123"
}

Parâmetros da Requisição

Parâmetros Gerais

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor total da transação em centavos, antes de descontos (mín. 500, máx. 20.000.000)
`payment`	object	Sim	Dados do pagamento (ver abaixo)
`customer`	object	Sim	Cliente por `id` ou inline (ver abaixo)
`billing`	object	Não*	`billing.address` — endereço do pagador (*obrigatório para boleto)
`items`	array	Não	Itemização do carrinho (máx. 100). Se enviado, Σ(`unitPrice`×`quantity`) deve igualar `amount`
`discounts`	array	Não	Cupons empilháveis (máx. 20). Cada item: `{ code }` (código do cupom no catálogo)
`splits`	array	Não	Splits de marketplace (máx. 10) — ver abaixo
`onBehalfOf`	string	Não	`publicId` de uma sub-conta sua: cobra direto na sub-conta com taxa de aplicação da plataforma
`geolocation`	object	Não	Sinais de geolocalização/dispositivo para antifraude (`ipAddress`, `latitude`, `longitude`, `deviceFingerprint`, `userAgent`, `acceptLanguage`)
`shipping`	object	Não	Bloco de entrega persistido como está e devolvido na leitura
`callback`	object	Não	`callback.webhookUrl` (url) + `callback.active` (default `true`): webhook específico desta transação
`description`	string	Não	Descrição livre (máx. 1000) — armazenada em `metadata.description`
`externalReference`	string	Não	Identificador externo (máx. 255)
`metadata`	object	Não	Metadados livres
`source`	string	Não	Origem da transação (máx. 20). Default: `api`

Parâmetros de Pagamento (payment)

Parâmetro	Tipo	Obrigatório	Descrição
`payment.method`	string	Sim	Método: `credit`, `pix` ou `billet`
`payment.currency`	string	Não	Moeda (apenas `BRL`). Default: `BRL`
`payment.installments`	integer	Não	Número de parcelas, 1–21. Default: `1`. (O máximo realmente ofertado é definido na conta e validado na cobrança — acima dele retorna 422 `installmentsExceedMax`.)
`payment.capture`	boolean	Não	Captura automática (`true`) ou manual/pré-autorização (`false`). Default: `true`. Aplica-se a crédito
`payment.financeInstallments`	boolean	Não	Default: `true`. Quando ligado, a API financia automaticamente o parcelamento, inflando o valor base para o total que o comprador pagaria com os juros configurados pelo vendedor (mesmo motor do simulador). Use `false` apenas se você já enviou o total financiado. Aplica-se a crédito com `installments > 1`

Cartão (payment.card) — para crédito

Forneça um cartão tokenizado (payment.card.id) ou os dados completos do cartão. Para method: "credit", um dos dois é obrigatório.

Parâmetro	Tipo	Obrigatório	Descrição
`payment.card.id`	string	Sim*	ID do cartão tokenizado (`card_...`). *Alternativa aos dados completos
`payment.card.holderName`	string	Sim**	Nome do titular. **Se `card.id` não for enviado
`payment.card.numbering`	string	Sim**	Número do cartão (validado por Luhn). **Se `card.id` não for enviado
`payment.card.expirationMonth`	string/integer	Sim**	Mês de expiração (1–12). **Se `card.id` não for enviado
`payment.card.expirationYear`	string/integer	Sim**	Ano de expiração. **Se `card.id` não for enviado
`payment.card.securityCode`	string	Sim**	CVV (3–4 dígitos). **Se `card.id` não for enviado

Boleto (payment.billet)

Parâmetro	Tipo	Obrigatório	Descrição
`payment.billet.expiresInDays`	integer	Não	Dias para expiração do boleto / vencimento (1–365). Se omitido, usa o default da conta
`payment.billet.billingInstructions`	object	Não	Multa/juros/desconto — ver billingInstructions. Se omitido, herda o default da conta

PIX (payment.pix)

Parâmetro	Tipo	Obrigatório	Descrição
`payment.pix.expiresInMinutes`	integer	Não	Minutos para expiração do PIX imediato (15–525600). Default do servidor: 30
`payment.pix.expiresInDays`	integer	Não	Presente ⇒ PIX com vencimento (cobv) — PIX datado (1–365), exige `customer` com documento. Ausente ⇒ PIX imediato
`payment.pix.billingInstructions`	object	Não	Somente `discounts` (cobv). `lateFee`/`interest` no PIX → 422 (multa/juros são exclusivos do boleto)

billingInstructions — multa / juros / desconto

Disponível no boleto (multa + juros + desconto) e no PIX com vencimento/cobv (somente desconto). Os três blocos são opcionais e independentes. Valores em centavos; percentuais 0–100; offsets de data relativos ao vencimento.

lateFee (multa por atraso)

Parâmetro	Tipo	Obrigatório	Descrição
`lateFee.mode`	string	Não (default `fixed`)	`fixed` (valor) ou `percentage` (% do boleto)
`lateFee.amount`	integer	se `mode=fixed`	Valor fixo em centavos
`lateFee.percentage`	number	se `mode=percentage`	Percentual 0–100
`lateFee.startDays`	integer	Não	Dias após o vencimento para começar a cobrar (carência), 0–60. `0` = a partir do vencimento

interest (juros)

Parâmetro	Tipo	Obrigatório	Descrição
`interest.mode`	string	Não (default `dailyAmount`)	`dailyAmount` (valor/dia), `dailyPercentage` (%/dia) ou `monthlyPercentage` (%/mês)
`interest.amount`	integer	se `mode=dailyAmount`	Valor fixo por dia, em centavos
`interest.percentage`	number	se `mode` percentual	Percentual 0–100
`interest.startDays`	integer	Não	Dias após o vencimento para começar a cobrar, 0–60

discounts[] (descontos por antecipação) — 1 a 3 faixas

Parâmetro	Tipo	Obrigatório	Descrição
`discounts[].mode`	string	Não (default `fixed`)	`fixed` (valor) ou `percentage`
`discounts[].amount`	integer	se `mode=fixed`	Valor fixo em centavos
`discounts[].percentage`	number	se `mode=percentage`	Percentual 0–100
`discounts[].daysBeforeDue`	integer	Não (default `0`)	Dias antes do vencimento até quando o desconto vale, 0–365. `0` = até o vencimento

Por adquirente: a Zoop suporta tudo; o Banco Inter ignora a carência (startDays) e o juros dailyPercentage, e usa apenas a 1ª faixa de discounts no boleto (no PIX cobv aceita múltiplas).

Cliente (customer) — por ID ou inline

Forneça customer.id (cliente já cadastrado) ou dados inline. Para o caminho inline, firstName + lastName + email são obrigatórios; os demais campos são opcionais. O endereço do pagador não vai aqui — vai em billing.address.

Parâmetro	Tipo	Obrigatório	Descrição
`customer.id`	string	Sim*	ID do cliente (`cus_...`). *Alternativa aos dados inline
`customer.firstName`	string	Sim**	Primeiro nome (mín. 2). **Se `customer.id` não for enviado
`customer.lastName`	string	Sim**	Sobrenome. **Se `customer.id` não for enviado
`customer.email`	string	Sim**	Email. **Se `customer.id` não for enviado
`customer.document.type`	string	Não	`cpf`, `cnpj` ou `passport`
`customer.document.number`	string	Não	Número do documento
`customer.telephone.countryCode`	string	Não	Código do país
`customer.telephone.areaCode`	string	Não	DDD
`customer.telephone.number`	string	Não	Número do telefone
`customer.gender`	string	Não	`male`, `female` ou `other`
`customer.birthdate`	string	Não	Data de nascimento (`YYYY-MM-DD`)
`customer.additionalEmails`	array	Não	Emails adicionais (máx. 20)
`customer.externalReference`	string	Não	Referência externa do cliente
`customer.metadata`	object	Não	Metadados do cliente

Endereço de cobrança (billing.address) — obrigatório para boleto

Forneça billing.address.id (endereço salvo) ou os campos inline. Para boleto, é obrigatório informar pelo menos postcode + street + number.

Parâmetro	Tipo	Descrição
`billing.address.id`	string	ID de endereço salvo (`addr_...`)
`billing.address.postcode`	string	CEP
`billing.address.street`	string	Logradouro
`billing.address.number`	string	Número
`billing.address.complement`	string	Complemento
`billing.address.district`	string	Bairro
`billing.address.city`	string	Cidade
`billing.address.state`	string	Estado
`billing.address.country`	string	País (2–3 letras)

Itens (items[])

Parâmetro	Tipo	Obrigatório	Descrição
`items[].name`	string	Sim	Nome do item
`items[].unitPrice`	integer	Sim	Preço unitário em centavos
`items[].quantity`	integer	Sim	Quantidade (1–100.000)
`items[].description`	string	Não	Descrição
`items[].currency`	string	Não	Moeda (`BRL`)
`items[].variantId`	string	Não	ID de variante de produto
`items[].images`	array	Não	URLs de imagens (máx. 10)
`items[].externalReference`	string	Não	Referência externa do item
`items[].metadata`	object	Não	Metadados do item

Parâmetros de Split (marketplace)

Cada split aceita o formato em valor fixo (recipientId + amountCents) ou o formato tipado (recipient + type + value). Máximo de 10 splits; a soma não pode exceder o valor cobrado.

Parâmetro	Tipo	Descrição
`splits[].recipientId` ou `splits[].recipient`	string	`publicId` da empresa destinatária
`splits[].amountCents`	integer	Valor fixo do split em centavos
`splits[].type`	string	`percentage` ou `flat` (alternativa a `amountCents`)
`splits[].value`	number	Percentual (≤ 100) ou valor, conforme `type`

3D Secure / cartão de débito / Nupay: o endpoint de criação não aceita um bloco threeDSecure, nem os métodos debit/nupay. (nupay é aceito apenas como filtro em Listar.)

Resposta

Sucesso (HTTP 201 Created)

Transações retidas para análise de fraude podem retornar HTTP 202 com status: "fraud-review".

{
  "id": "tra_987654321",
  "customId": "E5D4C3B2A1",
  "amount": 9500,
  "originalAmount": 10000,
  "status": "approved",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,
    "reusable": false,
    "billetUrl": null,
    "billetBarcode": null,
    "billetSequence": null,
    "billetDocumentNumber": null,
    "billetReferenceNumber": null,
    "pixQrCodeEmv": null,
    "pixQrCodeUrl": null,
    "pixQrCodeImage": null,
    "acquirerTransactionNumber": "9876543210987654321098765432",
    "cardFirstDigits": "553121",
    "cardLastDigits": "4567",
    "cardBrand": "Mastercard",
    "cardRegistered": true,
    "installments": 3,
    "expirationDate": null,
    "paidAt": "2026-03-10T14:23:45.000Z",
    "allowRenewPayment": false,
    "invoiceLink": "https://selectwin.io/invoices/tra_987654321"
  },
  "discount": {
    "value": 500,
    "type": "percentage",
    "percentageOfAmount": 5
  },
  "discounts": [
    {
      "source": "coupon",
      "couponId": 4821,
      "code": "SUMMER10",
      "type": "percentage",
      "value": 5,
      "appliedAmount": 500
    }
  ],
  "customer": {
    "id": "cus_987654321",
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "[email protected]",
    "birthdate": "1985-06-12",
    "gender": "female",
    "document": { "type": "cpf", "number": "98765432100" },
    "telephone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "987654321",
      "line": "5511987654321"
    },
    "available": true,
    "delinquent": false,
    "externalReference": "Store_Ref_54321",
    "additionalEmails": ["[email protected]"],
    "metadata": { "segment": "premium" },
    "updatedAt": "2026-03-05T10:20:48.000Z",
    "createdAt": "2026-01-15T08:30:48.000Z"
  },
  "billing": {
    "address": {
      "id": "addr_987654321",
      "ownerId": "cus_987654321",
      "ownerType": "customer",
      "street": "Avenida Paulista",
      "number": "2000",
      "complement": "Apto 501",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postcode": "01310200",
      "country": "BR",
      "latitude": "-23.5489",
      "longitude": "-46.638821",
      "line": "Avenida Paulista, 2000 - Apto 501, Bela Vista, São Paulo - SP, 01310200, BR",
      "line1": "Avenida Paulista, 2000",
      "line2": "Apto 501",
      "line3": "Bela Vista",
      "updatedAt": "2026-03-05T10:15:22.745Z",
      "createdAt": "2026-01-15T08:30:48.000Z"
    }
  },
  "shipping": null,
  "externalReference": "pedido_loja_9876",
  "shippable": true,
  "spplited": false,
  "items": [
    {
      "id": "item_987654321",
      "name": "Produto Premium",
      "unitPrice": 10000,
      "quantity": 1,
      "currency": "BRL",
      "description": "Produto de alta qualidade",
      "images": ["https://selectwin.io/assets/produto_premium.png"],
      "isUpsell": false,
      "isOrderbump": false,
      "metadata": { "sku": "PRM-001" },
      "variantId": null,
      "externalReference": null,
      "updatedAt": "2026-03-10T14:20:48.000Z",
      "createdAt": "2026-03-10T14:20:48.000Z"
    }
  ],
  "receivables": [
    {
      "id": "rec_987654321",
      "recipient": "bus_987654321",
      "split": null,
      "status": "paid",
      "amount": 9500,
      "grossAmount": 9500,
      "anticipationFee": 0,
      "installmentNumber": 1,
      "description": null,
      "currency": "BRL",
      "authorizationCode": "AUTH123456",
      "paidAt": "2026-03-10T14:25:30.000Z",
      "refundedAt": null,
      "canceledAt": null,
      "expectedOn": "2026-03-10T14:25:30.000Z",
      "liable": true,
      "chargeProcessingFee": true,
      "updatedAt": "2026-03-10T14:25:30.000Z",
      "createdAt": "2026-03-10T14:23:45.000Z"
    }
  ],
  "splits": null,
  "refunds": null,
  "disputes": null,
  "timeline": [
    {
      "id": "tl_123",
      "message": "Transaction approved",
      "details": null,
      "type": "status_change",
      "updatedAt": "2026-03-10T14:23:45.000Z",
      "createdAt": "2026-03-10T14:23:45.000Z"
    }
  ],
  "callback": {
    "webhookUrl": "https://meucomercio.com.br/webhook/notifications",
    "active": true
  },
  "metadata": {
    "source": "mobile_app",
    "campaign": "promo_verao_2026"
  },
  "processingTimeMs": 5523,
  "updatedAt": "2026-03-10T14:24:15.000Z",
  "createdAt": "2026-03-10T14:23:45.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions/tra_987654321",
      "method": "GET",
      "description": "Read a transaction."
    },
    "refund": {
      "href": "https://api.selectwin.io/v1/transactions/tra_987654321/refund",
      "method": "POST",
      "description": "Refund the transaction."
    },
    "capture": {
      "href": "https://api.selectwin.io/v1/transactions/tra_987654321/capture",
      "method": "POST",
      "description": "Capture the transaction."
    }
  }
}

Notas sobre a resposta

amount é o valor cobrado (após descontos/financiamento); originalAmount é o valor antes de descontos.
payment.version é "1.1" e payment.provider é "selectwin".
payment.pixQrCodeImage é sempre null (a API não gera imagem; use pixQrCodeEmv para renderizar o QR ou pixQrCodeUrl).
discount é o bloco legado consolidado ({ value, type, percentageOfAmount }), e discounts[] é o detalhamento por cupom aplicado ({ source, couponId, code, type, value, appliedAmount }). Ambos podem ser null quando não há desconto.
O customer da transação traz os dados do comprador, mas não embute as listas addresses/cards — para isso use GET /v1/customers/:id.
billing.address é um objeto aninhado dentro de billing (todos os campos podem ser null quando não há endereço).
processingTimeMs é o tempo de processamento do nosso backend para a cobrança, em milissegundos (de createdAt até o primeiro resultado do adquirente ser registrado). Vem null enquanto o resultado ainda não chegou e é carimbado uma única vez, no primeiro resultado — o mesmo valor aparece na leitura e no webhook transaction.*.
_links traz self, refund e capture.

Melhores Práticas

Use cartões tokenizados (payment.card.id) sempre que possível.
Utilize externalReference para rastrear a transação em seus sistemas.
Reaja a webhooks para acompanhar mudanças de status — não faça polling.
Defina expiração adequada para PIX e boleto.
Use X-Idempotency-Key em toda criação para evitar duplicidades.
Para captura manual, envie payment.capture: false e capture depois via Capturar.

Criar uma transação

On this page