Cria uma transação (cobrança)

POST/v1/transactions

Cria uma transação (cobrança) no cartão de crédito, no Pix ou no boleto (e no NuPay, nas contas habilitadas).

A criação é assíncrona. A resposta 201 vem pending (ou fraud-review) e o desfecho chega por webhook (transaction.approved, transaction.failed…). O copia e cola e o link do QR do Pix (payment.pixQrCodeEmv, payment.pixQrCodeUrl) e a linha digitável e o link do boleto (payment.billetBarcode, payment.billetUrl) não vêm na 201: chegam no webhook transaction.pending e ficam na leitura da transação.

Regras condicionais (a API confere; não estão no JSON Schema):

customer leva o id de um cliente salvo ou os dados inline (firstName, lastName e email).
payment.method=credit exige payment.card.id (cartão salvo), payment.card.token (cartão tokenizado no navegador) ou o cartão completo (holderName, expirationMonth, expirationYear, numbering, securityCode).
payment.method=billet exige billing.address.id (endereço salvo) ou o endereço inline (postcode, street, number).
payment.method=nupay exige payment.nupay.returnUrl e payment.nupay.cancelUrl, à vista e sem cartão; na conta não habilitada, 422 paymentMethodNotAvailable.
Se items[] for enviado, a soma de unitPrice × quantity deve ser igual a amount.
Desconto só por código de cupom do catálogo: discounts: [{ "code": "BEMVINDO10" }].

Veja os exemplos por método (credit / pix / billet / creditWithCart).

Autentique com o header SelectKey: a chave sk_test_ opera no sandbox, a sk_live_ em produção. Como autenticar.

Corpo da requisição

utmobject
Atribuição de marketing da venda: utm_source, utm_medium, utm_campaign, utm_content, utm_term (ou source, medium…).
itemsobject[]
Itens do carrinho (até 100).
+10 campos de items
- namestringobrigatório
  Nome do item.
- imagesstring (uri)[]
  URLs das imagens do item (até 10).
- pricingobject
  Apelido dos campos planos do item (unitPrice, quantity, currency), aninhados.
  +3 campos de pricing
  - currencystring
    Código de moeda ISO 4217
  - quantityinteger
    Quantidade.
  - unitPriceinteger
    Preço unitário, em centavos.
- currencystring
  Código de moeda ISO 4217
- metadataobject
  Objeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
- quantityintegerobrigatório
  Quantidade.
- unitPriceintegerobrigatório
  Preço unitário, em centavos.
- variantIdstring
  A variante do catálogo a que este item se refere, quando vem do seu catálogo.
- descriptionstring
  Descrição do item.
- externalReferencestring
  O seu próprio identificador do item.
amountintegerobrigatório
Valor em centavos, antes dos descontos (mínimo 500 = R$ 5,00). Com items[], precisa ser igual à soma de unitPrice × quantity.
sourcestring
De onde a venda veio (texto livre, até 20 caracteres).
splitsobject[]
Fatias desta cobrança destinadas a outras contas (até 10).
+5 campos de splits
- typestring
  percentage ou flat (com value).
  Valores:percentageflat
- valuenumber
  O percentual (0–100) ou o valor fixo em reais, conforme type.
- recipientstring
  Apelido de recipientId.
- amountCentsinteger
  Uma fatia fixa, em centavos.
- recipientIdstring
  A conta que recebe esta fatia (bus_…).
billingobject
Bloco de cobrança: o endereço do pagador. Regra: Obrigatório quando payment.method=billet (endereço do pagador): billing.address.id (salvo) ou endereço inline com postcode + street + number.
+1 campo de billing
- addressobjectobrigatório
  Endereço do pagador: um endereço salvo (id) ou os campos inline (postcode, street e number pelo menos). Obrigatório no boleto; guardado como retrato nos outros meios.
  +9 campos de address
  - idstring
    Um endereço salvo do comprador.
  - citystring
    Cidade.
  - statestring
    Estado (sigla de duas letras, ex.: SP).
  - numberstring
    Número.
  - streetstring
    Logradouro.
  - countrystring
    Código do país (ISO 3166-1, ex.: BR).
  - districtstring
    Bairro.
  - postcodestring
    CEP, 8 dígitos — o hífen é aceito.
  - complementstring
    Complemento (apartamento, sala, bloco…).
paymentobjectobrigatório
Como cobrar. Regra: Com method=credit, card é obrigatório (card.id de um cartão salvo, ou cartão completo inline: holderName, expirationMonth, expirationYear, numbering, securityCode).
+9 campos de payment
- pixobject
  Opções do Pix.
  +3 campos de pix
  - expiresInDaysinteger
    Presente = um Pix com vencimento (vence em tantos dias, como um boleto) no lugar do QR code imediato.
  - expiresInMinutesinteger
    Por quanto tempo o QR code fica pagável, em minutos (padrão das configurações da sua conta).
  - billingInstructionsobject
    Descontos por antecipação de um Pix com vencimento. Multa e juros não valem no Pix.
    +3 campos de billingInstructions
    lateFeeobject
    Multa depois do vencimento.
    +4 campos de lateFee
    modestring
    fixed (um valor) ou percentage (do boleto).
    Valores:fixedpercentage
    amountinteger
    A multa, em centavos (mode=fixed).
    startDaysinteger
    Dias depois do vencimento até a multa valer (0 = desde o vencimento).
    percentagenumber
    A multa, como percentual do boleto (mode=percentage).
    interestobject
    Juros depois do vencimento.
    +4 campos de interest
    modestring
    dailyAmount (centavos por dia), dailyPercentage ou monthlyPercentage.
    Valores:dailyAmountdailyPercentagemonthlyPercentage
    amountinteger
    Juros por dia, em centavos (mode=dailyAmount).
    startDaysinteger
    Dias depois do vencimento até os juros começarem (0 = desde o vencimento).
    percentagenumber
    Taxa de juros, como percentual por dia ou por mês, conforme mode.
    discountsobject[]
    Descontos por antecipação (1 a 3 faixas). Nem todo banco aplica mais do que a primeira.
    +4 campos de discounts
    modestring
    fixed (um valor) ou percentage (do boleto).
    Valores:fixedpercentage
    amountinteger
    O desconto, em centavos (mode=fixed).
    percentagenumber
    O desconto, como percentual do boleto (mode=percentage).
    daysBeforeDueinteger
    Dias antes do vencimento até quando o desconto vale (0 = até o vencimento).
- cardobject
  O cartão de uma cobrança no crédito: um cartão salvo (id), um token emitido no navegador do comprador (token), ou o cartão completo inline. O cartão inline é tokenizado antes da cobrança e nunca guardado.
  +7 campos de card
  - idstring
    Um cartão salvo do cliente.
  - tokenstring
    Token de cartão de uso único emitido no navegador do comprador por POST /v1/tokenization/tokens (válido por uma hora).
  - numberingstring
    Número do cartão (PAN), só dígitos — espaços e traços são removidos. Tokenizado ao chegar, nunca guardado.
  - holderNamestring
    Nome impresso no cartão (só no cartão inline).
  - securityCodestring
    Código de segurança do cartão (CVV/CVC), 3 ou 4 dígitos.
  - expirationYearobject
    Ano de validade, 4 dígitos — 2 dígitos são aceitos (só no cartão inline).
  - expirationMonthinteger
    Mês de validade, 1 a 12 (só no cartão inline).
- nupayobject
  Opções do NuPay — obrigatórias com method=nupay. A cobrança volta com payment.nupayPaymentUrl, onde o comprador a aprova.
  +4 campos de nupay
  - orderUrlstring (uri)
    A página do pedido na sua loja.
  - cancelUrlstring (uri)obrigatório
    Para onde o comprador volta depois de desistir.
  - returnUrlstring (uri)obrigatório
    Para onde o comprador volta depois de aprovar o pagamento no app.
  - expiresInMinutesinteger
    Quanto tempo o comprador tem para aprovar, em minutos (padrão das configurações da sua conta, senão 30).
- billetobject
  Opções do boleto.
  +2 campos de billet
  - expiresInDaysinteger
    Dias até o vencimento do boleto (padrão das configurações da sua conta).
  - billingInstructionsobject
    Multa, juros e descontos por antecipação do boleto.
    +3 campos de billingInstructions
    lateFeeobject
    Multa depois do vencimento.
    +4 campos de lateFee
    modestring
    fixed (um valor) ou percentage (do boleto).
    Valores:fixedpercentage
    amountinteger
    A multa, em centavos (mode=fixed).
    startDaysinteger
    Dias depois do vencimento até a multa valer (0 = desde o vencimento).
    percentagenumber
    A multa, como percentual do boleto (mode=percentage).
    interestobject
    Juros depois do vencimento.
    +4 campos de interest
    modestring
    dailyAmount (centavos por dia), dailyPercentage ou monthlyPercentage.
    Valores:dailyAmountdailyPercentagemonthlyPercentage
    amountinteger
    Juros por dia, em centavos (mode=dailyAmount).
    startDaysinteger
    Dias depois do vencimento até os juros começarem (0 = desde o vencimento).
    percentagenumber
    Taxa de juros, como percentual por dia ou por mês, conforme mode.
    discountsobject[]
    Descontos por antecipação (1 a 3 faixas). Nem todo banco aplica mais do que a primeira.
    +4 campos de discounts
    modestring
    fixed (um valor) ou percentage (do boleto).
    Valores:fixedpercentage
    amountinteger
    O desconto, em centavos (mode=fixed).
    percentagenumber
    O desconto, como percentual do boleto (mode=percentage).
    daysBeforeDueinteger
    Dias antes do vencimento até quando o desconto vale (0 = até o vencimento).
- methodstringobrigatório
  Meio de pagamento: credit (cartão), pix, billet (boleto) ou nupay.
  Valores:creditpixbilletnupay
- captureboolean
  true (padrão) captura na hora; false só pré-autoriza — capture depois com POST /v1/transactions/{id}/capture.
- currencystring
  Código de moeda ISO 4217
- installmentsinteger
  Número de parcelas (só cartão). O teto é o configurado na sua conta.
- financeInstallmentsboolean
  true (padrão): o comprador paga os juros de parcelamento configurados na sua conta, então amount é inflado até o total financiado — exatamente como o simulador mostra. Mande false só quando amount já for o total financiado.
callbackobject
Webhook só DESTA cobrança: os eventos dela vão para esta URL no lugar dos endpoints configurados na conta.
+2 campos de callback
- activeboolean
  Se o webhook próprio está ativo.
- webhookUrlstring (uri)obrigatório
  URL que recebe os webhooks desta cobrança.
customerobjectobrigatório
O comprador: um cliente salvo (id), ou os dados inline (firstName, lastName e email), que é encontrado ou criado. Regra: Obrigatório informar id (cliente salvo) OU os dados inline firstName + lastName + email (a API faz find-or-create). Enviar customer: {} é rejeitado.
+12 campos de customer
- idstring
  Um cliente salvo. Sem ele, o comprador é encontrado ou criado pelos campos inline.
- emailstring (email)
  Endereço de e-mail (obrigatório para criar o comprador inline).
- genderstring
  Gênero: male, female ou other.
  Valores:malefemaleother
- documentobject
  Documento do comprador.
  +2 campos de document
  - typestringobrigatório
    Tipo do documento: cpf, cnpj ou passport.
    Valores:cpfcnpjpassport
  - numberstringobrigatório
    Número do documento: dígitos do CPF ou CNPJ, ou o número do passaporte.
- fullNamestring
  Nome completo, como alternativa a nome + sobrenome.
- lastNamestring
  Sobrenome (obrigatório para criar o comprador inline).
- metadataobject
  Objeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
- birthdatestring
  Data de nascimento, YYYY-MM-DD.
- firstNamestring
  Nome (obrigatório para criar o comprador inline).
- telephoneobject
  Telefone do comprador, em partes; line é o número inteiro.
  +4 campos de telephone
  - linestring
    O número inteiro com código do país e DDD (ex.: 5511987654321) — o único telefone que chega ao provedor de pagamento (boleto, 3DS).
  - numberstring
    Número local, só dígitos.
  - areaCodestring
    DDD (ex.: 11).
  - countryCodestring
    Código do país (ex.: 55).
- additionalEmailsstring (email)[]
  Outros e-mails do comprador (até 20).
- externalReferencestring
  O seu próprio identificador do comprador.
metadataobject
Objeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
shippingobject
Retrato do frete (JSON livre): guardado como enviado e devolvido na leitura.
discountsobject[]
Códigos de cupom do seu catálogo (até 20), aplicados em ordem.
+1 campo de discounts
- codestringobrigatório
  Um código de cupom do seu catálogo.
onBehalfOfstring
Marketplace: cobrar NA sub-conta sua indicada — ela passa a ser a vendedora de registro e a sua taxa de plataforma é recolhida como split. Ausente = você é o vendedor.
descriptionstring
Nota em texto livre, guardada em metadata.description.
geolocationobject
Sinais de dispositivo e localização do comprador, para a análise de fraude. Todos opcionais: os cabeçalhos da requisição são usados quando omitidos.
+6 campos de geolocation
- latitudenumber
  Latitude do comprador.
- ipAddressum de
  Endereço IP do comprador.
  any
  any
- longitudenumber
  Longitude do comprador.
- userAgentstring
  User-Agent do navegador do comprador.
- acceptLanguagestring
  Accept-Language do navegador do comprador.
- deviceFingerprintstring
  Impressão digital do dispositivo, coletada pelo seu front-end.
externalReferencestring
O seu próprio identificador da cobrança (ex.: o número do seu pedido), devolvido como veio.

Respostas

201Criado

idstringobrigatório
Identificador público (tra_/trx_…)
netintegerobrigatório
O que você recebe: amount − fees, em centavos.
utmobjectobrigatóriopode ser nulo
Atribuição de marketing da venda; null quando não há.
+5 campos de utm
- termstring
  utm_term.
- mediumstring
  utm_medium.
- sourcestring
  utm_source.
- contentstring
  utm_content.
- campaignstring
  utm_campaign.
feesintegerobrigatório
Total de taxas retidas, em centavos.
itemsobject[]obrigatóriopode ser nulo
Itens do carrinho; null quando a cobrança não teve itens.
+14 campos de items
- idstringobrigatório
  Identificador público (item_/tri_…)
- namestringobrigatório
  Nome do item.
- imagesstring[]obrigatóriopode ser nulo
  URLs das imagens do item; null quando não há.
- currencystringobrigatóriopode ser nulo
  Moeda (ISO 4217).
- isUpsellbooleanobrigatóriopode ser nulo
  Se o item foi adicionado por uma oferta de upsell.
- metadataanypode ser nulo
  Os seus metadados chave-valor do item; null quando não há.
- quantityintegerobrigatório
  Quantidade.
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- unitPriceintegerobrigatório
  Preço unitário, em centavos.
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- variantIdstringobrigatóriopode ser nulo
  A variante do catálogo; null num item avulso.
- descriptionstringobrigatóriopode ser nulo
  Descrição do item.
- isOrderbumpbooleanobrigatóriopode ser nulo
  Se o item foi adicionado por um order bump.
- externalReferencestringobrigatóriopode ser nulo
  O seu próprio identificador do item; null quando não há.
_linksobject
Links para operações relacionadas, por ação (self, create, update, delete, list…).
amountintegerobrigatório
Valor cobrado, em centavos (depois dos descontos).
methodstringobrigatório
Meio de pagamento.
Valores:creditpixbilletnupay
splitsobject[]obrigatóriopode ser nulo
As fatias desta cobrança destinadas a outras contas; null quando não há split.
+10 campos de splits
- idstringobrigatóriopode ser nulo
  Id do split.
- amountintegerobrigatório
  Fatia líquida, em centavos.
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- recipientstringobrigatóriopode ser nulo
  A conta que recebe a fatia.
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- percentageum deobrigatóriopode ser nulo
  A fatia como percentual, quando foi definida assim.
  string
  number
- receivablestringobrigatóriopode ser nulo
  O recebível criado para a fatia.
- descriptionstringobrigatóriopode ser nulo
  Descrição.
- grossAmountintegerobrigatório
  Fatia bruta, em centavos.
- chargeProcessingFeebooleanobrigatóriopode ser nulo
  Se o recebedor paga a taxa de processamento da fatia.
statusstringobrigatório
Status da cobrança. A criação é assíncrona: o desfecho chega por webhook.
Valores:pendingpre-authorizedapprovedfailedrefusedcanceledrefundedchargebackdisputefraud-reviewanalyzingawaiting
billingobjectobrigatório
Bloco de cobrança.
+1 campo de billing
- addressobjectobrigatório
  O endereço do pagador.
  +19 campos de address
  - idstringobrigatóriopode ser nulo
    Id do endereço; null quando o endereço não foi salvo.
  - citystringobrigatóriopode ser nulo
    Cidade.
  - linestringobrigatóriopode ser nulo
    O endereço inteiro numa linha.
  - line1stringobrigatóriopode ser nulo
    Primeira linha: logradouro e número.
  - line2stringobrigatóriopode ser nulo
    Segunda linha: bairro.
  - line3stringobrigatóriopode ser nulo
    Terceira linha: cidade, estado e CEP.
  - statestringobrigatóriopode ser nulo
    Estado (sigla de duas letras).
  - numberstringobrigatóriopode ser nulo
    Número.
  - streetstringobrigatóriopode ser nulo
    Logradouro.
  - countrystringobrigatóriopode ser nulo
    Código do país (ISO 3166-1).
  - ownerIdstringobrigatóriopode ser nulo
    Id público do dono do endereço.
  - districtstringobrigatóriopode ser nulo
    Bairro.
  - latitudeum deobrigatóriopode ser nulo
    Latitude; null quando desconhecida.
    string
    number
  - postcodestringobrigatóriopode ser nulo
    CEP, só dígitos.
  - createdAtstringobrigatóriopode ser nulo
    Quando o recurso foi criado (ISO 8601, UTC).
  - longitudeum deobrigatóriopode ser nulo
    Longitude; null quando desconhecida.
    string
    number
  - ownerTypestringobrigatóriopode ser nulo
    Quem é dono do endereço (customer, company…).
  - updatedAtstringobrigatóriopode ser nulo
    Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
  - complementstringobrigatóriopode ser nulo
    Complemento (apartamento, sala, bloco…).
paymentobjectobrigatório
Como a cobrança é paga: o código Pix, o boleto, o cartão usado, a recusa.
+25 campos de payment
- cardIdstringobrigatóriopode ser nulo
  Id público (card_…) do cartão que esta cobrança usou, quando ficou salvo no cliente — o mesmo que GET /v1/cards lista. Use-o para cobrar renovações com payment.card.id. null sem cartão.
- paidAtstringobrigatóriopode ser nulo
  Quando a cobrança foi paga; null até lá.
- refusedobjectobrigatóriopode ser nulo
  Por que a cobrança foi recusada; null quando não foi.
  +6 campos de refused
  - codestringobrigatório
    Código estável da recusa — o valor para tratar no seu sistema.
    Valores:insufficientFundsErrorexpiredCardErrorinvalidCardNumberinvalidExpiryMonthinvalidExpiryYearinvalidSecurityCodeinvalidPinCodeinvalidPaymentInformationcardDeclinedauthorizationRefusedcardCustomerNotAssociatedinvalidParameterssellerAuthorizationRefusedpaymentMethodUnavailablepixAutomaticNotDebitedcardValidationUnavailablepaymentProcessingError
  - typestringobrigatório
    Família do erro: cardError, invalidRequestError ou processingError.
    Valores:cardErrorinvalidRequestErrorprocessingError
  - messagestringobrigatório
    Mensagem técnica (em inglês).
  - categorystringobrigatório
    payment, validation, businessRule ou processing.
    Valores:paymentvalidationbusinessRuleprocessing
  - reversiblebooleanobrigatório
    Se o comprador pode tentar de novo (ex.: com outro cartão).
  - displayMessagestringobrigatório
    Mensagem segura para mostrar ao comprador (pt-BR).
- versionstringobrigatório
  Versão do objeto de pagamento.
  Valores:1.1
- providerstringobrigatório
  Sempre selectwin.
  Valores:selectwin
- reusablebooleanobrigatório
  Se o pagamento pode ser reutilizado (hoje sempre false).
- billetUrlstringobrigatóriopode ser nulo
  URL do boleto (PDF); null nos outros meios e até ser emitido.
- cardBrandstringobrigatóriopode ser nulo
  Bandeira do cartão.
- invoiceLinkstringobrigatóriopode ser nulo
  URL do comprovante hospedado desta cobrança (pay.selectwin.io/r/…). null na resposta da criação — preenchido na leitura e nos webhooks.
- installmentsintegerobrigatóriopode ser nulo
  Número de parcelas.
- pixQrCodeEmvstringobrigatóriopode ser nulo
  Código copia e cola do Pix (EMV); null até ser emitido.
- pixQrCodeUrlstringobrigatóriopode ser nulo
  URL da imagem do QR code do Pix.
- billetBarcodestringobrigatóriopode ser nulo
  Linha digitável do boleto.
- billetSequencestringobrigatóriopode ser nulo
  Número sequencial do boleto.
- cardLastDigitsstringobrigatóriopode ser nulo
  Quatro últimos dígitos do cartão.
- cardRegisteredbooleanobrigatório
  Se o cartão foi salvo no cliente.
- expirationDatestringobrigatóriopode ser nulo
  Quando o Pix ou o boleto expira; null em cartão.
- pixQrCodeImagestringobrigatóriopode ser nulo
  Imagem do QR code do Pix (base64); null quando não disponível.
- cardFirstDigitsstringobrigatóriopode ser nulo
  Seis primeiros dígitos do cartão; null nos outros meios.
- invoicePathLinkstringobrigatóriopode ser nulo
  O mesmo comprovante, como caminho (/r/{env}/{token}) para renderizar no seu próprio domínio. null exatamente quando invoiceLink é.
- nupayPaymentUrlstringpode ser nulo
  NuPay: o link de aprovação no app do Nubank, para onde o comprador é enviado. null nos outros meios.
- allowRenewPaymentbooleanobrigatório
  Se um novo Pix/boleto pode ser emitido para esta cobrança (true nesses meios).
- billetDocumentNumberstringobrigatóriopode ser nulo
  Número do documento do boleto.
- billetReferenceNumberstringobrigatóriopode ser nulo
  Número de referência do boleto.
- acquirerTransactionNumberstringobrigatóriopode ser nulo
  Número da cobrança no provedor de pagamento (NSU).
refundsobject[]obrigatóriopode ser nulo
Os estornos feitos nesta cobrança; null quando não há.
+8 campos de refunds
- idstringobrigatório
  Identificador público (void_/trf_/trr_…)
- amountintegerobrigatório
  Valor estornado, em centavos.
- categorystringobrigatóriopode ser nulo
  Categoria do estorno (ver GET /v1/utils/types-of-refund).
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- receiptIdum deobrigatóriopode ser nulo
  Comprovante do estorno.
  string
  number
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- descriptionstringobrigatóriopode ser nulo
  Por que foi estornado.
- observationsstringobrigatóriopode ser nulo
  Observações.
callbackobjectobrigatóriopode ser nulo
Webhook só desta cobrança; null quando não há.
+2 campos de callback
- activebooleanobrigatóriopode ser nulo
  Se o webhook próprio está ativo.
- webhookUrlstringobrigatóriopode ser nulo
  URL que recebe os webhooks desta cobrança.
currencystringobrigatório
Moeda (ISO 4217).
customIdstringobrigatóriopode ser nulo
O seu id personalizado da cobrança: prefixo + base + sufixo, como configurado em /v1/companies/configs; null em cobranças antigas.
customerobjectobrigatóriopode ser nulo
O comprador; null quando não há.
+15 campos de customer
- idstringobrigatório
  Identificador público (cus_…)
- emailstringobrigatóriopode ser nulo
  Endereço de e-mail; null quando não há.
- genderstringobrigatóriopode ser nulo
  Gênero (male, female, other); null quando desconhecido.
- documentobjectobrigatório
  Documento do comprador.
  +2 campos de document
  - typestringobrigatóriopode ser nulo
    Tipo do documento; null quando não há.
  - numberstringobrigatóriopode ser nulo
    Número do documento (dígitos em CPF/CNPJ); null quando não há.
- lastNamestringobrigatóriopode ser nulo
  Sobrenome.
- metadataanypode ser nulo
  Os seus metadados chave-valor; null quando não há.
- availablebooleanobrigatóriopode ser nulo
  Se o cliente está ativo e pode ser cobrado.
- birthdatestringobrigatóriopode ser nulo
  Data de nascimento (YYYY-MM-DD); null quando desconhecida.
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- firstNamestringobrigatóriopode ser nulo
  Nome.
- telephoneobjectobrigatório
  Telefone do comprador, em partes.
  +4 campos de telephone
  - linestringobrigatóriopode ser nulo
    O número inteiro com código do país e DDD.
  - numberstringobrigatóriopode ser nulo
    Número local.
  - areaCodestringobrigatóriopode ser nulo
    DDD.
  - countryCodestringobrigatóriopode ser nulo
    Código do país.
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- delinquentbooleanobrigatóriopode ser nulo
  Se o cliente tem pagamentos em atraso.
- additionalEmailsanypode ser nulo
  Outros e-mails do comprador; null quando não há.
- externalReferencestringobrigatóriopode ser nulo
  O seu próprio identificador deste cliente; null quando não há.
discountobjectobrigatóriopode ser nulo
Desconto aplicado à cobrança; null quando não há.
+3 campos de discount
- typestringobrigatório
  flat ou percentage.
- valueintegerobrigatório
  O desconto, em centavos.
- percentageOfAmountnumberobrigatóriopode ser nulo
  O desconto como percentual do valor.
disputesobject[]obrigatóriopode ser nulo
As disputas desta cobrança; null quando não há.
+19 campos de disputes
- idstringobrigatóriopode ser nulo
  Id da disputa.
- reasonstringobrigatóriopode ser nulo
  Por que o comprador contestou.
- statusstringobrigatóriopode ser nulo
  Status da disputa.
- outcomestringobrigatóriopode ser nulo
  Como terminou: won (a cobrança volta a aprovada) ou lost (chargeback); null enquanto aberta.
  Valores:wonlost
- closedAtstringobrigatóriopode ser nulo
  Quando foi encerrada; null enquanto aberta.
- deadlineobjectobrigatóriopode ser nulo
  O prazo das provas, derivado de openedAt; null quando a data de abertura é desconhecida.
  +4 campos de deadline
  - urgentbooleanobrigatório
    Ainda defensável, mas perto do prazo.
  - expiredbooleanobrigatório
    A janela fechou: provas enviadas agora não são mais aceitas.
  - deadlineAtstringobrigatóriopode ser nulo
    Até quando as provas são aceitas.
  - hoursRemainingnumberobrigatóriopode ser nulo
    Horas restantes para enviar as provas.
- openedAtstringobrigatóriopode ser nulo
  Quando a disputa foi aberta.
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- decidedAtstringobrigatóriopode ser nulo
  Quando foi decidida; null enquanto aberta.
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- reasonCodestringobrigatóriopode ser nulo
  Código do motivo na bandeira.
- descriptionstringobrigatóriopode ser nulo
  O texto da sua defesa.
- returnEmailstringobrigatóriopode ser nulo
  E-mail que recebe o desfecho.
- deliveryProofanypode ser nulo
  Prova de entrega que você anexou; null quando não há.
- shipmentProofanypode ser nulo
  Prova de envio que você anexou; null quando não há.
- fiscalDocumentsanypode ser nulo
  Documentos fiscais que você anexou; null quando não há.
- deliveryReceiptsanypode ser nulo
  Comprovantes de entrega que você anexou; null quando não há.
- reasonDescriptionstringobrigatóriopode ser nulo
  Descrição do motivo.
- communicationProofanypode ser nulo
  Prova de comunicação que você anexou; null quando não há.
merchantobject
A conta dona do recurso (o vendedor de registro).
+3 campos de merchant
- namestringobrigatóriopode ser nulo
  Nome fantasia da conta dona do recurso.
- merchantIdstringobrigatóriopode ser nulo
  Id público da conta dona do recurso (bus_…).
- isSubAccountbooleanobrigatório
  true quando o recurso pertence a uma sub-conta operada por uma plataforma de marketplace.
metadataanypode ser nulo
Os seus metadados chave-valor; null quando não há.
shippinganypode ser nulo
Retrato do frete, como enviado; null quando não há.
spplitedbooleanobrigatório
Se a cobrança foi dividida com outras contas (ver splits). O nome mantém a grafia histórica.
timelineobject[]obrigatório
Histórico da cobrança (mudanças de status e notas), do mais antigo ao mais novo.
+6 campos de timeline
- idstringobrigatóriopode ser nulo
  Id da entrada.
- typestringobrigatóriopode ser nulo
  Tipo da entrada.
- detailsstringobrigatóriopode ser nulo
  Detalhes da entrada.
- messagestringobrigatóriopode ser nulo
  O que aconteceu.
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
createdAtstringobrigatório
Quando o recurso foi criado (ISO 8601, UTC).
discountsany[]obrigatóriopode ser nulo
Os cupons aplicados; null quando não há.
shippablebooleanobrigatório
Se a venda tem itens físicos para enviar.
updatedAtstringobrigatório
Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
receivablesobject[]obrigatóriopode ser nulo
Os recebíveis desta cobrança, um por parcela e recebedor; null quando ainda não há.
+19 campos de receivables
- idstringobrigatóriopode ser nulo
  Id do recebível (rec_…).
- splitstringobrigatóriopode ser nulo
  O split de que vem; null quando é seu.
- amountintegerobrigatório
  Valor líquido, em centavos.
- liablebooleanobrigatóriopode ser nulo
  Se este recebedor arca com os chargebacks dele.
- paidAtstringobrigatóriopode ser nulo
  Quando foi liberado ao recebedor; null até lá.
- statusstringobrigatóriopode ser nulo
  Status do recebível.
- currencystringobrigatóriopode ser nulo
  Moeda (ISO 4217).
- createdAtstringobrigatóriopode ser nulo
  Quando o recurso foi criado (ISO 8601, UTC).
- recipientstringobrigatóriopode ser nulo
  A conta que o recebe.
- updatedAtstringobrigatóriopode ser nulo
  Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
- canceledAtstringobrigatóriopode ser nulo
  Quando foi cancelado; null quando não foi.
- expectedOnstringobrigatóriopode ser nulo
  Data prevista de liberação.
- refundedAtstringobrigatóriopode ser nulo
  Quando foi estornado; null quando não foi.
- descriptionstringobrigatóriopode ser nulo
  Descrição.
- grossAmountintegerobrigatório
  Valor bruto, em centavos.
- anticipationFeeintegerobrigatóriopode ser nulo
  Taxa cobrada para antecipá-lo, em centavos; null quando não foi antecipado.
- authorizationCodestringobrigatóriopode ser nulo
  Código de autorização da cobrança.
- installmentNumberintegerobrigatóriopode ser nulo
  Número da parcela a que pertence.
- chargeProcessingFeebooleanobrigatóriopode ser nulo
  Se este recebedor paga a taxa de processamento.
paymentGroupobjectpode ser nulo
Pagamento combinado: esta cobrança é UMA PARTE de um pedido pago com dois cartões ou cartão + Pix. null = venda comum.
+8 campos de paymentGroup
- idstringobrigatório
  Id do pedido (o grupo de pagamento).
- methodstringobrigatório
  dualcredit (dois cartões) ou creditpix (cartão + Pix).
  Valores:dualcreditcreditpix
- statusstringobrigatório
  Status do pedido inteiro — feche o pedido por ele, nunca por uma parte.
  Valores:authorizingawaiting_retryawaiting_pixcapturingpaidcompensatingfailedcanceledneeds_review
- legCountintegerobrigatório
  Número de partes do pedido.
- legIndexintegerobrigatório
  Posição desta parte no pedido (a partir de 0).
- isPrimarybooleanobrigatório
  Se é a parte principal do pedido.
- totalAmountintegerobrigatório
  Total do pedido, em centavos.
- transactionIdsstring[]
  A cobrança atual de cada parte do pedido, na ordem das partes (esta inclusa).
originalAmountintegerobrigatório
Valor antes dos descontos, em centavos.
processingTimeMsintegerobrigatóriopode ser nulo
Tempo da criação até o primeiro resultado do pagamento, em milissegundos; null até lá.
externalReferencestringobrigatóriopode ser nulo
O seu próprio identificador da cobrança; null quando não há.

400Requisição inválida (validação)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

401Não autenticado (credencial ausente ou inválida)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

403Sem permissão

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

404Não encontrado

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

409Conflito (idempotência ou estado)

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

422Regra de negócio impede o processamento

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

500Erro interno do servidor

errorobjectobrigatório
+8 campos de error
- codestringobrigatório
- paramsobject[]
- statusstringobrigatório
- detailsstring
- messagestringobrigatório
- categorystringobrigatório
  Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
- resourcestringobrigatório
- statusCodeintegerobrigatório

AnteriorLista as transações PróximaConsulta uma transação

Requisição

Exemplo

curl -X POST "https://api.selectwin.io/v1/transactions" \
  -H "SelectKey: $SELECTWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "payment": {
    "pix": {
      "expiresInMinutes": 60
    },
    "method": "pix"
  },
  "customer": {
    "id": "cus_0a1b2c3d4e5f60718293"
  },
  "externalReference": "PEDIDO-123"
}'

Resposta

Exemplo

{
  "id": "tra_0a1b2c3d4e5f60718293",
  "net": 4751,
  "utm": null,
  "fees": 249,
  "items": null,
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions/tra_0a1b2c3d4e5f60718293",
      "method": "GET",
      "description": "Read a transaction."
    },
    "refund": {
      "href": "https://api.selectwin.io/v1/transactions/tra_0a1b2c3d4e5f60718293/refund",
      "method": "POST",
      "description": "Refund the transaction."
    },
    "capture": {
      "href": "https://api.selectwin.io/v1/transactions/tra_0a1b2c3d4e5f60718293/capture",
      "method": "POST",
      "description": "Capture the transaction."
    }
  },
  "amount": 5000,
  "method": "pix",
  "splits": null,
  "status": "pending",
  "billing": {
    "address": {
      "id": null,
      "city": null,
      "line": null,
      "line1": null,
      "line2": null,
      "line3": null,
      "state": null,
      "number": null,
      "street": null,
      "country": null,
      "ownerId": null,
      "district": null,
      "latitude": null,
      "postcode": null,
      "createdAt": null,
      "longitude": null,
      "ownerType": null,
      "updatedAt": null,
      "complement": null
    }
  },
  "payment": {
    "cardId": null,
    "paidAt": null,
    "refused": null,
    "version": "1.1",
    "provider": "selectwin",
    "reusable": false,
    "billetUrl": null,
    "cardBrand": null,
    "invoiceLink": null,
    "installments": 1,
    "pixQrCodeEmv": null,
    "pixQrCodeUrl": null,
    "billetBarcode": null,
    "billetSequence": null,
    "cardLastDigits": null,
    "cardRegistered": false,
    "expirationDate": "2026-01-15T13:00:00.000Z",
    "pixQrCodeImage": null,
    "cardFirstDigits": null,
    "invoicePathLink": null,
    "nupayPaymentUrl": null,
    "allowRenewPayment": true,
    "billetDocumentNumber": null,
    "billetReferenceNumber": null,
    "acquirerTransactionNumber": null
  },
  "refunds": null,
  "callback": null,
  "currency": "BRL",
  "customId": "K7M8N9P2Q3RS",
  "customer": {
    "id": "cus_0a1b2c3d4e5f60718293",
    "email": "joao.silva@example.com",
    "gender": null,
    "document": {
      "type": "cpf",
      "number": "12345678909"
    },
    "lastName": "Silva",
    "metadata": null,
    "available": true,
    "birthdate": "1990-05-20",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "firstName": "João",
    "telephone": {
      "line": "5511987654321",
      "number": "987654321",
      "areaCode": "11",
      "countryCode": "55"
    },
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "delinquent": false,
    "additionalEmails": null,
    "externalReference": null
  },
  "discount": null,
  "disputes": null,
  "merchant": {
    "name": "Acme Ltda",
    "merchantId": "bus_0a1b2c3d4e5f60718293",
    "isSubAccount": false
  },
  "metadata": null,
  "shipping": null,
  "spplited": false,
  "timeline": [],
  "createdAt": "2026-01-15T12:00:00.000Z",
  "discounts": null,
  "shippable": false,
  "updatedAt": "2026-01-15T12:00:00.000Z",
  "receivables": null,
  "originalAmount": 5000,
  "processingTimeMs": null,
  "externalReference": "PEDIDO-123"
}