Cria uma sessão de checkout

POST/v1/checkouts/sessions

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 (source, medium, campaign, content, term). Capturada uma vez; imutável na atualização.
itemsobject[]
O carrinho: um objeto por linha (id da variante, quantity…). Validado contra o seu catálogo quando a sessão é enviada para pagamento.
clientobject
Dados do cliente, incluindo a UTM da primeira visita (JSON livre; imutável depois da primeira inicialização).
sourcestring
De onde a sessão veio (texto livre, até 20 caracteres).
addressobject
O endereço, como preenchido até agora (JSON livre).
ambientstring
Aceito por compatibilidade; o ambiente vem sempre da sua credencial.
Valores:livesandbox
cookiesobject
Cookies de rastreio do comprador, pelo nome do cookie (_fbp, _fbc, _ga, gclid…), para a atribuição dos pixels.
couponsum de[]
Cupons aplicados: códigos, ou objetos com code.
customerobject
O comprador, como preenchido até agora (JSON livre).
languagestring
Idioma do comprador (ex.: pt-BR).
metadataobject
Os seus metadados chave-valor.
timezonestring
Fuso horário do comprador (ex.: America/Sao_Paulo).
totalTaxinteger
Total de impostos, em centavos.
expiresAtstring (date-time)
Quando a sessão expira; derivado das suas configurações quando omitido.
lineItemsobject[]
Apelido de items.
onBehalfOfstring
Marketplace: a cobrança que esta sessão liquida é feita NA sub-conta sua indicada (ela passa a ser a vendedora de registro); a sua taxa de plataforma é recolhida como split.
totalAmountinteger
Total do carrinho, em centavos.
redirectUrlsobject
Para onde o comprador é enviado depois do pagamento, por desfecho (paid, refused, pending): URLs https://; vazio ou null = não definido.
integrationIdstring
Id público dessa integração.
totalDiscountinteger
Total de desconto, em centavos.
totalShippinginteger
Total do frete, em centavos.
paymentMethodsum de[]
Meios de pagamento oferecidos nesta sessão.
integrationTypestring
Tipo da integração a que a sessão pertence (ex.: woocommerce).
shippingDeliveryobject
A opção de frete escolhida (JSON livre).
externalTransactionIdstring
O id do seu pedido para esta sessão.

Respostas

201Criado

idstringobrigatório
Identificador público (sess_/ckts_/ses_…)
urlstringobrigatóriopode ser nulo
URL do checkout hospedado desta sessão; null quando não há.
utmobjectobrigatóriopode ser nulo
Atribuição de marketing; null quando não há.
objectstringobrigatório
Sempre checkout.session.
Valores:checkout.session
onlinebooleanobrigatório
Se o comprador está no checkout agora (um sinal recente da página).
sourcestringobrigatóriopode ser nulo
De onde a sessão veio; null quando desconhecido.
statusstringobrigatório
active (o comprador está no checkout), completed (pago), cancelled, abandoned ou expired.
Valores:activecompletedcancelledabandonedexpired
totalsobjectobrigatório
Os totais do carrinho; todos null quando nunca foi precificado.
+4 campos de totals
- taxintegerobrigatóriopode ser nulo
  Total de impostos, em centavos.
- amountintegerobrigatóriopode ser nulo
  Total do carrinho, em centavos; null quando o carrinho nunca foi precificado.
- discountintegerobrigatóriopode ser nulo
  Total de desconto, em centavos.
- shippingintegerobrigatóriopode ser nulo
  Total do frete, em centavos.
addressobjectobrigatóriopode ser nulo
O endereço, como preenchido; null quando ainda não há nada.
ambientstringobrigatório
Ambiente: live ou sandbox.
cookiesobjectobrigatóriopode ser nulo
Cookies de rastreio do comprador, pelo nome do cookie; null quando não há.
couponsobject[]obrigatório
Cupons aplicados.
+3 campos de coupons
- codestringobrigatóriopode ser nulo
  Código do cupom.
- typestringobrigatóriopode ser nulo
  flat ou percentage.
- valuenumberobrigatóriopode ser nulo
  O valor do desconto.
currencystringobrigatório
Sempre BRL.
Valores:BRL
customerobjectobrigatóriopode ser nulo
O comprador, como preenchido; null quando ainda não há nada.
metadataobjectobrigatóriopode ser nulo
Os seus metadados chave-valor; null quando não há.
createdAtstringobrigatório
Quando o recurso foi criado (ISO 8601, UTC).
expiresAtstringobrigatóriopode ser nulo
Quando a sessão expira.
lineItemsobject[]obrigatório
O carrinho.
+9 campos de lineItems
- idstringobrigatóriopode ser nulo
  A variante do catálogo; null num item avulso.
- namestringobrigatóriopode ser nulo
  Nome do item.
- currencystringobrigatório
  Moeda (ISO 4217).
- isUpsellbooleanobrigatório
  Se o item foi adicionado por uma oferta de upsell.
- metadataobjectobrigatóriopode ser nulo
  Os seus metadados chave-valor do item; null quando não há.
- quantityintegerobrigatório
  Quantidade.
- unitPricenumberobrigatóriopode ser nulo
  Preço unitário, em centavos; null quando ainda não precificado.
- isOrderbumpbooleanobrigatório
  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á.
updatedAtstringobrigatório
Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).
customInputsanyobrigatóriopode ser nulo
Sempre null.
Valores:null
redirectUrlsobjectobrigatório
Para onde o comprador é enviado depois do pagamento, por desfecho.
+3 campos de redirectUrls
- paidstringobrigatóriopode ser nulo
  Para onde o comprador vai depois de um pedido pago.
- pendingstringobrigatóriopode ser nulo
  Para onde o comprador vai enquanto o pagamento está pendente.
- refusedstringobrigatóriopode ser nulo
  Para onde o comprador vai depois de uma recusa.
integrationIdstringobrigatóriopode ser nulo
Id público dessa integração; null quando não há.
paymentMethodsum de[]obrigatório
Meios de pagamento oferecidos.
integrationTypestringobrigatóriopode ser nulo
Tipo da integração a que a sessão pertence; null quando não há.
paymentSelectionobjectobrigatóriopode ser nulo
O meio de pagamento que o comprador escolheu; null até lá.
+1 campo de paymentSelection
- methodstringobrigatório
  O meio escolhido.
firstInitializationbooleanobrigatório
Se é a primeira vez que a sessão foi inicializada.
externalTransactionIdstringobrigatóriopode ser nulo
O id do seu pedido; 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

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 sessões de checkout PróximaLista os links de pagamento

Requisição

curl -X POST "https://api.selectwin.io/v1/checkouts/sessions" \
  -H "SelectKey: $SELECTWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "utm": {},
  "items": [],
  "client": {},
  "source": "string",
  "address": {},
  "ambient": "live",
  "cookies": {},
  "coupons": [
    "string"
  ],
  "customer": {},
  "language": "string",
  "metadata": {},
  "timezone": "string",
  "totalTax": 5000,
  "expiresAt": "2026-01-15T12:00:00.000Z",
  "lineItems": [
    {}
  ],
  "onBehalfOf": "id_0a1b2c3d4e5f60718293",
  "totalAmount": 5000,
  "redirectUrls": {},
  "integrationId": "string",
  "totalDiscount": 5000,
  "totalShipping": 5000,
  "paymentMethods": [
    "string"
  ],
  "integrationType": "string",
  "shippingDelivery": {},
  "externalTransactionId": "string"
}'

Resposta

{
  "id": "sess_0a1b2c3d4e5f60718293",
  "url": "string",
  "utm": {},
  "object": "checkout.session",
  "online": true,
  "source": "string",
  "status": "active",
  "totals": {
    "tax": 0,
    "amount": 5000,
    "discount": 0,
    "shipping": 0
  },
  "address": {},
  "ambient": "string",
  "cookies": {},
  "coupons": [
    {
      "code": "string",
      "type": "string",
      "value": 5000
    }
  ],
  "currency": "BRL",
  "customer": {},
  "metadata": {},
  "createdAt": "string",
  "expiresAt": "string",
  "lineItems": [
    {
      "id": "string",
      "name": "Acme Ltda",
      "currency": "BRL",
      "isUpsell": true,
      "metadata": {},
      "quantity": 0,
      "unitPrice": 5000,
      "isOrderbump": true,
      "externalReference": "string"
    }
  ],
  "updatedAt": "string",
  "customInputs": "null",
  "redirectUrls": {
    "paid": "string",
    "pending": "string",
    "refused": "string"
  },
  "integrationId": "string",
  "paymentMethods": [
    "string"
  ],
  "integrationType": "string",
  "paymentSelection": {
    "method": "string"
  },
  "firstInitialization": true,
  "externalTransactionId": "string"
}