Transações - Criar

#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), boleto (billet) e, nas contas habilitadas, NuPay (nupay), 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), e multa/juros/desconto no boleto.

#Precauções

• Métodos de Pagamento: na criação são aceitos credit, pix, billet e nupay (este só nas contas habilitadas para o NuPay; nas outras, 422 paymentMethodNotAvailable). Forneça todos os dados obrigatórios para o método escolhido (cartão para crédito; endereço de cobrança para boleto; payment.nupay.returnUrl e payment.nupay.cancelUrl para NuPay, e o CPF ou CNPJ do comprador: sem documento válido, 422 customerDocumentRequired).
• 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.
• 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.

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 409 (Conflict) com code: "idempotencyMismatch".

#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": "joao.silva@exemplo.com",
    "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": "maria.souza@exemplo.com",
    "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": "carlos.ferreira@exemplo.com",
    "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" } }
}

#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" }
}

Regras da pilha (as mesmas do checkout — HTTP 422):

#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) 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

#Atribuição (UTM)

O objeto utm diz de onde veio a venda. Ele fica guardado na transação e é a dimensão que os relatórios de canal agrupam — sem ele, a venda aparece como (direto).

{
  "utm": {
    "source": "instagram",
    "medium": "cpc",
    "campaign": "lancamento-agosto",
    "content": "criativo-v2",
    "term": "curso-online",
    "fbclid": "IwAR1x...",
    "gclid": "Cj0KCQ..."
  }
}

Duas grafias entram, uma sai. Aceitamos source, utm_source e utmSource — a URL do anúncio carimba utm_source, e é normal repassá-la crua. O que é armazenado e devolvido é sempre a forma curta (source). Chave desconhecida é descartada; valor vazio, null ou o texto literal "null"/"undefined" é tratado como ausente (um objeto só de nulos equivale a não enviar utm).

Apenas os cinco campos UTM são consultáveis; os identificadores de clique são guardados junto, mas não são dimensão de relatório.

#Parâmetros de Pagamento (payment)

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

Forneça um cartão salvo (payment.card.id), um token do navegador (payment.card.token, ver Tokenização no navegador) ou os dados completos do cartão. Para method: "credit", um dos três é obrigatório.

#Boleto (payment.billet)

#PIX (payment.pix)

#billingInstructions — multa / juros / desconto

Disponível no boleto (multa + juros + 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)

interest (juros)

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

#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.

#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.

#Itens (items[])

#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.

#Resposta

#Sucesso (HTTP 201 Created)

{
  "id": "tra_987654321",
  "customId": "E5D4C3B2A1",
  "amount": 9500,
  "originalAmount": 10000,
  "fees": 475,
  "net": 9025,
  "status": "pending",
  "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,
    "nupayPaymentUrl": null,
    "pixQrCodeImage": null,
    "acquirerTransactionNumber": null,
    "cardFirstDigits": "553121",
    "cardLastDigits": "4567",
    "cardBrand": "Mastercard",
    "cardRegistered": true,
    "cardId": "card_987654321",
    "installments": 3,
    "expirationDate": null,
    "paidAt": null,
    "allowRenewPayment": false,
    "invoiceLink": null,
    "invoicePathLink": null
  },
  "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": "maria.silva@exemplo.com",
    "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": ["maria.trabalho@exemplo.com"],
    "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": null,
  "splits": null,
  "refunds": null,
  "disputes": null,
  "timeline": [],
  "callback": {
    "webhookUrl": "https://meucomercio.com.br/webhook/notifications",
    "active": true
  },
  "metadata": {
    "source": "mobile_app",
    "campaign": "promo_verao_2026"
  },
  "utm": null,
  "processingTimeMs": null,
  "updatedAt": "2026-03-10T14:23:45.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."
    }
  }
}

#Onde chegam o QR do Pix e a linha digitável do boleto

A resposta 201 vem pending e ainda sem os dados de pagamento do Pix e do boleto (os campos vêm null). Eles chegam logo depois, no webhook transaction.pending, e ficam na leitura da transação (GET /v1/transactions/{id}):

O pagamento confirmado chega como transaction.approved. Veja o Catálogo de Eventos.

#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

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