> ## Documentation Index > Fetch the complete documentation index at: https://nexus-docs.ticto.dev/llms.txt > Use this file to discover all available pages before exploring further. # Criar checkout > Cria um novo checkout para processamento de pagamento. **Campos obrigatórios:** - `offer_code` - Código da oferta - `payment_method` - Método de pagamento (opcional quando a oferta principal é gratuita e não há bumps pagos) - `installments` - Número de parcelas (opcional nas mesmas condições de `payment_method`) - `customer` **ou** `customer_code` - Dados do cliente (objeto) ou código de cliente já existente - `card_token` **ou** `card_code` - Apenas quando `payment_method` for `credit_card` **Campos obrigatórios para produtos físicos:** - `freight_value` - Valor do frete em centavos - `freight_method` - Método de envio (pac, sedex, by_producer) - `freight_type` - Tipo de frete (free, fixed, shipping_company) - `customer_address` - Endereço completo de entrega **Observações:** - Para produtos digitais (course, ebook), os campos de frete e endereço não são necessários - Para produtos físicos, todos os campos de frete e endereço são obrigatórios - O formato canônico do endereço é `customer_address` (top-level). Compatível com `customer_code` sem enviar o objeto `customer` - O formato legado `customer.address` (aninhado) ainda é aceito e normalizado automaticamente para `customer_address` pelo Nexus - Quando ambos forem enviados, `customer_address` tem precedência - O campo `freight_days` é opcional, mas recomendado - Os campos `complement` e `reference` do endereço são opcionais, mas devem ser enviados explicitamente (mesmo que como `null`) quando o endereço estiver presente - Para produtos físicos com `blocked_states` configurado no frete da oferta, o checkout será recusado (HTTP 422) se o estado do endereço do cliente estiver na lista de estados bloqueados ## OpenAPI ````yaml /api-reference/openapi.yaml post /financial/checkout openapi: 3.0.3 info: title: Nexus version: 1.0.2 description: > API para integração entre Ticto e clientes externos # Autenticação Para autenticar as solicitações aos endpoints descritos a seguir, por favor, siga os passos abaixo: 1. **Solicite** seu cadastro como cliente através do e-mail **infraestrutura@ticto.com.br** para obter seu `client_id` e `token`. 2. **Use** seu token e ID de cliente para fazer login no Nexus e obter seu `client_token`. 3. **Em todas as outras requisições**, envie seu `client_token` no header como `X-Api-Client-Token`. 4. **Crie** seus usuários na rota de criação de usuário. Para cada usuário, será retornado um `public_token` único. 5. **Para endpoints que não estão em public.php**, adicione o `public_token` do usuário no cabeçalho **Authorization** utilizando o formato: ```http Authorization: Bearer {public_token} ``` ## Restrição de origem O acesso a esta API não está disponível para todos os sellers. Seu uso é estritamente permitido para parceiros comerciais que a utilizarão em cenários específicos. Por este motivo, o acesso será restrito a endereços IP e domínios previamente informados por esses parceiros. Essa medida visa proporcionar um ambiente mais controlado e seguro para todos os nossos usuários e parceiros. ### O que isso significa para os desenvolvedores? - **Acesso Limitado:** Somente os IPs e domínios pré-autorizados poderão realizar chamadas à API. Qualquer tentativa de acesso de um IP ou domínio não listado será automaticamente rejeitada. - **Processo de Autorização:** Para garantir a continuidade do acesso à API sem interrupções, é essencial que os desenvolvedores enviem os endereços IP ou domínios que necessitam de acesso diretamente à nossa equipe de suporte. - **Como Solicitar Acesso:** Envie um e-mail para **liberacao@ticto.com.br** com o assunto _"Solicitação de Acesso à API de pagamentos"_, incluindo: - Nome da empresa ou do desenvolvedor - Endereços IP ou domínios a serem autorizados - Justificativa para o acesso - Informações de contato para eventuais esclarecimentos ## Alterações e/ou inclusão de novos domínios e IPs Recomendamos que solicitações de adição ou alteração de IPs/domínios sejam feitas o mais breve possível para garantir uma transição suave. Em casos de alterações, os domínios e/ou IPs anteriores serão imediatamente bloqueados após sua remoção. ## Suporte e Dúvidas Para dúvidas ou suporte adicional, entre em contato conosco através do e-mail **liberacao@ticto.com.br**. Estamos comprometidos em auxiliar neste processo e garantir a melhor experiência possível. servers: - url: https://nexus.ticto.com.br/api/v1 description: Produção security: [] tags: - name: Autenticação - name: Configurações do Cliente - name: Usuários - name: Onboarding de usuário - name: Contas Bancárias - name: Faixas de Taxa description: >- Endpoints para consulta de faixas de taxa personalizadas e histórico de alterações. - name: Frete - name: Financeiro - name: PIX Automático description: >- Consulta, cancelamento e nova tentativa de cobrança de assinaturas com PIX Automático (débito recorrente autorizado pelo pagador). - name: Produtos - name: Integrações - name: 'Webhooks: Usuários' description: Eventos relacionados a cadastro e atualização de usuários. - name: 'Webhooks: Contas Bancárias' description: Eventos relacionados a contas bancárias dos sellers. - name: 'Webhooks: Produtos e Ofertas' description: Eventos relacionados a produtos, ofertas, afiliados e coprodutores. - name: 'Webhooks: Financeiro' description: Eventos de reembolso, saque e antecipação. - name: 'Webhooks: Faixas de Taxa' description: Eventos de criação, atualização e exclusão de faixas de taxa. - name: 'Webhooks: Pedidos' description: Eventos de criação e atualização de pedidos. - name: 'Webhooks: Cobranças' description: >- Eventos de criação e mudança de status de cobranças (transações), na primeira compra e nas renovações. - name: 'Webhooks: Assinaturas' description: Eventos do ciclo de vida de assinaturas, cobranças e trial. paths: /financial/checkout: post: tags: - Financeiro summary: Criar checkout description: > Cria um novo checkout para processamento de pagamento. **Campos obrigatórios:** - `offer_code` - Código da oferta - `payment_method` - Método de pagamento (opcional quando a oferta principal é gratuita e não há bumps pagos) - `installments` - Número de parcelas (opcional nas mesmas condições de `payment_method`) - `customer` **ou** `customer_code` - Dados do cliente (objeto) ou código de cliente já existente - `card_token` **ou** `card_code` - Apenas quando `payment_method` for `credit_card` **Campos obrigatórios para produtos físicos:** - `freight_value` - Valor do frete em centavos - `freight_method` - Método de envio (pac, sedex, by_producer) - `freight_type` - Tipo de frete (free, fixed, shipping_company) - `customer_address` - Endereço completo de entrega **Observações:** - Para produtos digitais (course, ebook), os campos de frete e endereço não são necessários - Para produtos físicos, todos os campos de frete e endereço são obrigatórios - O formato canônico do endereço é `customer_address` (top-level). Compatível com `customer_code` sem enviar o objeto `customer` - O formato legado `customer.address` (aninhado) ainda é aceito e normalizado automaticamente para `customer_address` pelo Nexus - Quando ambos forem enviados, `customer_address` tem precedência - O campo `freight_days` é opcional, mas recomendado - Os campos `complement` e `reference` do endereço são opcionais, mas devem ser enviados explicitamente (mesmo que como `null`) quando o endereço estiver presente - Para produtos físicos com `blocked_states` configurado no frete da oferta, o checkout será recusado (HTTP 422) se o estado do endereço do cliente estiver na lista de estados bloqueados operationId: createCheckout requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestCheckout' examples: physical_product: summary: Checkout com produto físico description: >- Exemplo recomendado de checkout para produto físico com frete e endereço no formato canônico `customer_address` value: offer_code: O994032E5 payment_method: pix installments: 1 customer: name: João Silva email: joao.silva@test.com document: '84742753003' phone: '11987654321' customer_address: zip_code: '01310100' city: São Paulo state: SP country: Brasil street: Avenida Paulista street_number: '1578' neighborhood: Bela Vista complement: Apto 101 reference: Próximo ao metrô freight_value: 3462 freight_method: pac freight_type: shipping_company freight_days: 8 discount_amount: 0 order_items: [] physical_product_customer_code: summary: Checkout com produto físico (customer_code) description: >- Exemplo de checkout para produto físico usando cliente existente via `customer_code` e endereço em `customer_address` value: offer_code: O994032E5 payment_method: pix installments: 1 customer_code: U1A2B3C4D customer_address: zip_code: '01310100' city: São Paulo state: SP country: Brasil street: Avenida Paulista street_number: '1578' neighborhood: Bela Vista complement: null reference: null freight_value: 3462 freight_method: pac freight_type: shipping_company freight_days: 8 discount_amount: 0 order_items: [] physical_product_nested_address_legacy: summary: Checkout com produto físico (customer.address legado) description: >- Formato legado com endereço aninhado em `customer.address`. Aceito por compatibilidade e normalizado automaticamente para `customer_address` pelo Nexus. value: offer_code: O994032E5 payment_method: pix installments: 1 customer: name: João Silva email: joao.silva@test.com document: '84742753003' phone: '11987654321' address: zip_code: '01310100' city: São Paulo state: SP country: Brasil street: Avenida Paulista street_number: '1578' neighborhood: Bela Vista complement: Apto 101 reference: Próximo ao metrô freight_value: 3462 freight_method: pac freight_type: shipping_company freight_days: 8 discount_amount: 0 order_items: [] digital_product: summary: Checkout com produto digital description: >- Exemplo de checkout para produto digital (sem frete e endereço) value: offer_code: O12345678 payment_method: credit_card installments: 3 customer: name: Maria Santos email: maria.santos@test.com document: '12345678909' phone: '11999887766' card_token: tok_test_abc123xyz discount_amount: 0 order_items: [] pix_recurring: summary: Checkout com PIX Automático description: >- Assinatura paga por PIX Automático. A oferta precisa ser recorrente, ter `allow_pix_recurring` habilitado e o produtor precisa ter o PIX Automático liberado pela Ticto. value: offer_code: O7R3C0RR3 payment_method: pix_recurring installments: 1 customer: name: Maria Santos email: maria.santos@test.com document: '12345678909' phone: '11999887766' discount_amount: 0 order_items: [] responses: '201': description: Checkout criado com sucesso content: application/json: schema: $ref: '#/components/schemas/ResponseCheckout' examples: with_freight: summary: Response com frete description: Resposta para checkout de produto físico value: status: success message: Recurso criado com sucesso. data: hash: TOP0412WJO18IY amount: 15000 discount: 0 installments: 1 created_at: 04/12/2025 13:17:37 freight: value: 3462 type: shipping_company method: pac days: 8 customer: name: João Silva email: joao.silva@test.com code: 7KCMDSUYJP1764715168 public_token: TIC-0cb5d556-fbab-4d0c-85d1-0bfc96f55e03 items: - type: main amount: 15000 status: waiting_payment quantity: 1 subtotal: 15000 subtotal_discount: 0 offer: name: Physical Offer QA Updated code: O994032E5 type_of_charge: one-time price: 15000 transaction: hash: TPP3DBB0412WQ38AJY payment: pix: qr_code: >- 00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/6f61fd6130c84867b16de368fd5670a25204000053039865802BR5921Ticto Tecnologia Ltda6008Campinas62070503***630462BB without_freight: summary: Response sem frete description: Resposta para checkout de produto digital value: status: success message: Recurso criado com sucesso. data: hash: TOP0412XYZ123 amount: 5000 discount: 0 installments: 3 created_at: 04/12/2025 14:00:00 freight: null customer: name: Maria Santos email: maria.santos@test.com code: ABC123XYZ public_token: TIC-xyz123-4567-8901-2345-6789abcdef01 items: - type: main amount: 5000 status: waiting_payment quantity: 1 subtotal: 5000 subtotal_discount: 0 offer: name: Curso Online code: O12345678 type_of_charge: one-time price: 5000 transaction: hash: TPP3DBB0412XYZ123 payment: credit_card: brand: visa last4: '1234' installments: 3 with_pix_recurring: summary: Response com PIX Automático description: >- O pagador escaneia `payment.pix_recurring.qr_code` uma vez para autorizar o mandato. As cobranças seguintes são debitadas sem nova ação dele. value: status: success message: Recurso criado com sucesso. data: hash: TOP2909PIXR001 amount: 9700 discount: 0 installments: 1 created_at: 29/09/2026 10:00:00 freight: null customer: name: Maria Santos email: maria.santos@test.com code: ABC123XYZ public_token: TIC-xyz123-4567-8901-2345-6789abcdef01 items: - type: main amount: 9700 status: waiting_payment quantity: 1 subtotal: 9700 subtotal_discount: 0 offer: name: Assinatura mensal code: O7R3C0RR3 type_of_charge: recurring price: 9700 transaction: hash: TPP3DBB2909PIXR01 payment: pix_recurring: qr_code: >- 00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/... external_id: '5738293847561728' authorization_url: null status: pending authorized: false frequency: monthly expires_at: null '400': description: Requisição inválida '401': description: Não autorizado '422': description: Payload incorreto '500': description: Erro interno do servidor security: - ApiClientToken: [] components: schemas: RequestCheckout: type: object required: - offer_code description: > Os campos `payment_method` e `installments` são obrigatórios exceto quando a oferta principal é gratuita (price = 0) e não há order bumps pagos. properties: customer: type: object required: - name - email properties: name: type: string maxLength: 320 description: Nome do cliente email: type: string format: email maxLength: 320 description: Email do cliente document: type: string maxLength: 18 description: >- CPF/CNPJ do cliente. Obrigatório quando `is_foreign` não é `true`. Quando `is_foreign = true`, o campo é opcional e pode ser `null`. phone: type: string description: Telefone do cliente is_foreign: type: boolean description: >- Indica cliente estrangeiro. Quando true, o document deixa de ser obrigatório. address: type: object deprecated: true description: > Formato legado de endereço aninhado no objeto `customer`. Ainda aceito por compatibilidade e normalizado automaticamente para `customer_address` pelo Nexus. Prefira enviar o endereço em `customer_address`. required: - zip_code - city - state - country - street - street_number - neighborhood properties: zip_code: type: string description: CEP (obrigatório para produtos físicos) example: '01310100' city: type: string description: Cidade (obrigatório para produtos físicos) example: São Paulo state: type: string maxLength: 2 description: Sigla do estado (obrigatório para produtos físicos) example: SP country: type: string description: País (obrigatório para produtos físicos) example: Brasil street: type: string description: Nome da rua (obrigatório para produtos físicos) example: Avenida Paulista street_number: type: string maxLength: 8 description: Número do endereço (obrigatório para produtos físicos) example: '1578' neighborhood: type: string description: Bairro (obrigatório para produtos físicos) example: Bela Vista complement: type: string nullable: true description: >- Complemento do endereço (opcional, mas deve ser enviado explicitamente como null se não houver) example: Apto 101 reference: type: string nullable: true description: >- Ponto de referência (opcional, mas deve ser enviado explicitamente como null se não houver) example: Próximo ao metrô customer_address: type: object description: > Endereço de entrega no formato canônico (top-level). Obrigatório para produtos físicos. Pode ser enviado junto com `customer` ou com `customer_code`. Quando `customer.address` (formato legado) também for enviado, este campo tem precedência. required: - zip_code - city - state - country - street - street_number - neighborhood properties: zip_code: type: string description: CEP (obrigatório para produtos físicos) example: '01310100' city: type: string description: Cidade (obrigatório para produtos físicos) example: São Paulo state: type: string maxLength: 2 description: Sigla do estado (obrigatório para produtos físicos) example: SP country: type: string description: País (obrigatório para produtos físicos) example: Brasil street: type: string description: Nome da rua (obrigatório para produtos físicos) example: Avenida Paulista street_number: type: string maxLength: 8 description: Número do endereço (obrigatório para produtos físicos) example: '1578' neighborhood: type: string description: Bairro (obrigatório para produtos físicos) example: Bela Vista complement: type: string nullable: true description: >- Complemento do endereço (opcional, mas deve ser enviado explicitamente como null se não houver) example: Apto 101 reference: type: string nullable: true description: >- Ponto de referência (opcional, mas deve ser enviado explicitamente como null se não houver) example: Próximo ao metrô customer_code: type: string description: Código do cliente (alternativa ao objeto customer) card_token: type: string description: Token do cartão (obrigatório para pagamento com cartão) card_code: type: string description: Código do cartão (alternativa ao card_token) offer_code: type: string description: Código da oferta discount_amount: type: number description: Valor do desconto installments: type: integer minimum: 1 maximum: 12 description: Número de parcelas payment_method: type: string enum: - credit_card - pix - bank_slip - pix_recurring description: > Método de pagamento. - `pix_recurring` (PIX Automático): exige oferta recorrente (`type_of_charge=recurring`) com `allow_pix_recurring` habilitado e o PIX Automático liberado para o produtor na Ticto (liberação feita pela Ticto, não disponível via API; ver `allow_pix_recurring` em Ofertas). Sem isso o checkout é recusado com 422. A resposta traz `payment.pix_recurring.qr_code`, que o pagador escaneia uma vez para autorizar o débito recorrente. freight_value: type: integer minimum: 0 description: Valor do frete em centavos (obrigatório para produtos físicos) example: 3462 freight_method: type: string enum: - pac - sedex - by_producer description: Método de envio (obrigatório para produtos físicos) example: pac freight_type: type: string enum: - free - fixed - shipping_company description: Tipo de frete (obrigatório para produtos físicos) example: shipping_company freight_days: type: integer minimum: 0 description: Prazo de entrega em dias úteis (opcional) example: 8 order_items: type: array description: Itens adicionais do pedido (order bumps). Campo opcional. items: type: object required: - offer_code - type properties: offer_code: type: string description: Código da oferta do bump type: type: string enum: - bump description: Tipo do item (apenas 'bump') quantity: type: integer minimum: 1 description: Quantidade do item (opcional, padrão 1) pid: type: string nullable: true description: Identificador do PID do checkout pids: type: array minItems: 1 maxItems: 2 description: Lista de PIDs do checkout (valores distintos, máximo 2) items: type: string fgpt_id: type: string nullable: true description: Identificador de fingerprint do checkout (rastreamento anti-fraude) ResponseCheckout: type: object required: - items properties: hash: type: string description: Hash do checkout amount: type: integer minimum: 0 maximum: 99999999 description: Valor total do checkout em centavos discount: type: integer minimum: 0 maximum: 99999999 description: Valor do desconto aplicado em centavos installments: type: integer minimum: 1 maximum: 36 description: Número de parcelas platform_fee: type: integer nullable: true description: Taxa percentual da plataforma em centavos (pode ser null) platform_fixed_fee: type: integer nullable: true description: Taxa fixa da plataforma em centavos (pode ser null) created_at: type: string nullable: true description: Data de criação (formato dd/mm/aaaa HH:MM:SS) example: 04/12/2025 13:17:37 freight: type: object description: >- Informações de frete (presente apenas para produtos físicos, pode ser null para produtos digitais) properties: value: type: integer description: Valor do frete em centavos example: 3462 type: type: string enum: - free - fixed - shipping_company description: Tipo de frete example: shipping_company method: type: string enum: - pac - sedex - by_producer description: Método de envio (null quando type !== 'shipping_company') example: pac days: type: integer description: Prazo de entrega em dias úteis example: 8 customer: type: object properties: name: type: string description: Nome do cliente email: type: string format: email description: Email do cliente code: type: string description: Código do cliente public_token: type: string description: Token público do cliente items: type: array description: Lista de itens do checkout items: type: object properties: type: type: string description: Tipo do item (main, bump, combo) amount: type: integer minimum: 0 maximum: 99999999 status: type: string quantity: type: integer minimum: 1 maximum: 999999 subtotal: type: integer minimum: 0 maximum: 99999999 subtotal_discount: type: integer minimum: 0 maximum: 99999999 offer: type: object properties: name: type: string description: Nome da oferta code: type: string description: Código da oferta type_of_charge: type: string description: Tipo de cobrança price: type: integer minimum: 0 maximum: 99999999 description: Preço da oferta transaction: type: object nullable: true description: Dados da transação properties: hash: type: string description: Hash da transação payment: type: object properties: bank_slip: type: object description: Informações do boleto properties: code: type: string description: Código do boleto due_date: type: string description: Vencimento do boleto url: type: string format: url description: URL do boleto pix: type: object description: Informações de pagamento via PIX avulso properties: qr_code: type: string description: Código QR para pagamento imediato via PIX pix_recurring: type: object description: >- Informações de autorização de PIX Automático. Presente quando `payment_method=pix_recurring`. O cliente escaneia o QR code uma única vez para autorizar o mandato de débito recorrente junto ao banco. As cobranças subsequentes são debitadas automaticamente, sem nova ação do cliente. properties: qr_code: type: string description: >- QR code de autorização do mandato de débito automático. Validade de 30 minutos. external_id: type: string nullable: true description: Identificador da autorização no gateway de pagamento. authorization_url: type: string nullable: true description: URL de autorização do mandato, quando o gateway fornece uma. status: type: string nullable: true description: Status atual do mandato (ver `PixRecurringStatus`). authorized: type: boolean nullable: true description: Se o pagador já autorizou o mandato. frequency: type: string nullable: true description: >- Frequência de cobrança do mandato (ver `PixRecurringFrequency`). expires_at: type: string nullable: true description: Data de expiração da autorização. credit_card: type: object description: Informações do cartão de crédito properties: brand: type: string description: Bandeira do cartão last4: type: string description: Últimos 4 dígitos do cartão installments: type: integer minimum: 1 maximum: 36 description: Parcelas no cartão customer_address: type: object description: >- Endereço de entrega persistido no checkout (presente quando um endereço foi enviado na requisição, em qualquer formato aceito) properties: zip_code: type: string street: type: string street_number: type: string country: type: string city: type: string state: type: string neighborhood: type: string complement: type: string nullable: true reference: type: string nullable: true comissions: description: | Comissões da venda (presente apenas quando aplicável). Observação: a chave é retornada com a grafia `comissions`. nullable: true subscription: type: object description: Informações da assinatura properties: code: type: string description: Código da assinatura price: type: integer minimum: 0 maximum: 99999999 description: Preço da assinatura interval: type: string description: Intervalo da cobrança free_days: type: integer minimum: 0 maximum: 365 description: Dias grátis antes da cobrança next_charge: type: string format: date-time description: Próxima cobrança successful_charges: type: integer minimum: 0 maximum: 999999 description: Quantidade de cobranças bem-sucedidas failed_charges: type: integer minimum: 0 maximum: 999999 description: Quantidade de cobranças com erro securitySchemes: ApiClientToken: type: apiKey in: header name: X-Api-Client-Token description: Token de autenticação do cliente obtido via endpoint /auth ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.