> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Cobrança

> Cria uma nova cobrança (pedido de pagamento). Suporta os métodos de pagamento: **CreditCard**, **PIX**. Requer o header `account` com o código da conta. Passa por validações de fraude, bloqueio de clientes e rate limiting.

Possíveis cenários de resposta:
- **201** — Cobrança processada com sucesso (aprovada ou aguardando pagamento PIX)
- **202** — Transação desafiada (requer confirmação adicional via OTP)
- **400** — Fraude detectada ou erro no processamento do gateway
- **422** — Erro de validação dos dados enviados


<Note>
  Requer o header `account` com o código da conta. Passa por validações de fraude, bloqueio de clientes e rate limiting por cliente.
</Note>

<Warning>
  Clientes bloqueados por IP, e-mail, CPF ou BIN do cartão terão a cobrança rejeitada automaticamente.
</Warning>


## OpenAPI

````yaml POST /v1/charge
openapi: 3.1.0
info:
  title: 4Selet Pay API
  description: >
    API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
    cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
    rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
  version: 1.0.0
  contact:
    name: 4Selet Pay
    email: suporte@4selet.com.br
servers:
  - url: https://sandbox.4seletpay.com.br/api
    description: Servidor de Sandbox
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Rotas de autenticação e criação de usuários
  - name: Cobranças
    description: Criação, consulta, cancelamento e reembolso de cobranças
  - name: Pedidos
    description: Consulta de pedidos e gerenciamento de confirmações desafiadas
  - name: Assinaturas
    description: Criação e gerenciamento de assinaturas recorrentes
  - name: Faturas
    description: Gerenciamento de faturas e pagamento de faturas em atraso
  - name: Clientes Bloqueados
    description: Gerenciamento de lista negra de clientes
  - name: Contas
    description: Criação e gerenciamento de contas na plataforma
  - name: Aplicativo
    description: Endpoints para dashboard e uso via aplicativo mobile
  - name: Notificações Push
    description: Envio e gerenciamento de notificações push
  - name: Utilitários
    description: Endpoints utilitários como listagem de fusos horários
  - name: Gestão
    description: Relatórios gerenciais (acesso restrito a Super Admins)
  - name: Webhooks
    description: Endpoints para receber notificações de gateways de pagamento
  - name: Endpoints de Webhook
    description: >-
      Gerenciamento de endpoints de webhook para receber notificações de eventos
      da plataforma
  - name: Links de Pagamento
    description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
paths:
  /v1/charge:
    post:
      tags:
        - Cobranças
      summary: Criar cobrança
      description: >
        Cria uma nova cobrança (pedido de pagamento). Suporta os métodos de
        pagamento: **CreditCard**, **PIX**. Requer o header `account` com o
        código da conta. Passa por validações de fraude, bloqueio de clientes e
        rate limiting.


        Possíveis cenários de resposta:

        - **201** — Cobrança processada com sucesso (aprovada ou aguardando
        pagamento PIX)

        - **202** — Transação desafiada (requer confirmação adicional via OTP)

        - **400** — Fraude detectada ou erro no processamento do gateway

        - **422** — Erro de validação dos dados enviados
      operationId: createCharge
      parameters:
        - $ref: '#/components/parameters/AccountHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            examples:
              cartao_credito:
                summary: Pagamento com Cartão de Crédito
                value:
                  international: false
                  client:
                    name: João Silva
                    email: joao@exemplo.com.br
                    gender: Male
                    birthdate: '1990-01-15'
                    phone:
                      ddi: '55'
                      ddd: '11'
                      number: '999999999'
                    document:
                      type: CPF
                      number: 123.456.789-09
                    address:
                      zipcode: 01310-100
                      street: Avenida Paulista
                      number: 1000
                      neighborhood: Bela Vista
                      complement: Apto 42
                      city: São Paulo
                      state: SP
                      country: Brasil
                  payment:
                    type: CreditCard
                    card:
                      number: '4111111111111111'
                      name: JOAO SILVA
                      month: '12'
                      year: '27'
                      security_code: '123'
                      installments: 1
                      soft_descriptor: MINHA LOJA
                  items:
                    - id: produto_001
                      description: Camiseta Premium
                      amount: 99.9
                      quantity: 2
              pix:
                summary: Pagamento com PIX
                value:
                  international: false
                  client:
                    name: Maria Santos
                    email: maria@exemplo.com.br
                    phone:
                      ddi: '55'
                      ddd: '21'
                      number: '988887777'
                    document:
                      type: CPF
                      number: 987.654.321-00
                  payment:
                    type: PIX
                    pix_expiration: 3600
                  items:
                    - id: curso_001
                      description: Curso Online
                      amount: 297
                      quantity: 1
      responses:
        '201':
          description: Cobrança processada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCreateResponse'
              example:
                mensagem: Cobrança realizada com sucesso.
                erro: false
                mensagenserro: []
                codigoretorno: 201
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                data:
                  charge_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  charge_created_at: 11/03/2026 10:00:00
                  account_id: 1
                  code: pur_abc123xyz
                  value: 199.8
                  charge_value: 199.8
                  coin: BRL
                  status: Approved
                  client:
                    code: cli_abc123
                    name: João Silva
                    email: joao@exemplo.com.br
                  orders:
                    - code: ord_abc123xyz
                      status: Approved
                      value: 199.8
                      charges:
                        - code: chg_abc123
                          status: Approved
                          value: 199.8
                          installments: 1
                          payment:
                            payment_type: CreditCard
                            installments: 1
        '202':
          description: Transação desafiada — requer confirmação adicional (OTP)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCreateResponse'
              example:
                mensagem: A transação necessita de confirmação...
                erro: false
                mensagenserro: []
                codigoretorno: 202
                id: 00000000-0000-0000-0000-000000000000
                data:
                  charge_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  status: Challenged
                  orders:
                    - code: ord_abc123xyz
                      status: Challenged
                      confirmation_codes:
                        - id: conf_xyz789
                          type: OTP
                          status: Pending
                          expires_at: '2026-03-11T10:15:00.000000Z'
        '400':
          description: Fraude detectada ou erro no gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                mensagem: Não foi possível concluir sua transação.
                erro: true
                mensagenserro:
                  - Verifique as informações e tente novamente.
                codigoretorno: 400
                id: 00000000-0000-0000-0000-000000000000
                data: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountHeader:
      name: account
      in: header
      required: true
      description: Código da conta à qual a operação se aplica
      schema:
        type: string
        example: acc_abc123xyz
  schemas:
    CheckoutRequest:
      type: object
      required:
        - client
        - payment
        - items
      properties:
        international:
          type: boolean
          nullable: true
          description: Indica se é uma transação internacional (opcional, padrão false)
          example: false
        client:
          $ref: '#/components/schemas/ClientData'
        payment:
          $ref: '#/components/schemas/PaymentData'
        items:
          type: array
          description: Lista de itens da compra (obrigatório, mín. 1 item)
          items:
            $ref: '#/components/schemas/ItemData'
          example:
            - id: produto_001
              description: Camiseta Premium
              amount: 99.9
              quantity: 2
    ChargeCreateResponse:
      type: object
      description: >-
        Resposta da criação de cobrança (envelope APIReturnUtil + dados
        ConsultCharge)
      properties:
        mensagem:
          type: string
          example: Cobrança realizada com sucesso.
        erro:
          type: boolean
          example: false
        mensagenserro:
          type: array
          items:
            type: string
          example: []
        codigoretorno:
          type: integer
          example: 201
        id:
          type: string
          description: ID da cobrança criada
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        data:
          $ref: '#/components/schemas/ChargeConsultData'
    ErrorResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: Um erro inesperado acabou de acontecer.
        erro:
          type: boolean
          example: true
        mensagenserro:
          type: array
          items:
            type: string
          example:
            - Detalhe do erro ocorrido.
        codigoretorno:
          type: integer
          example: 400
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        data:
          type: array
          example: []
    ClientData:
      type: object
      required:
        - name
        - email
        - phone
      properties:
        name:
          type: string
          description: Nome completo do cliente (obrigatório, máx. 255 caracteres)
          example: João Silva
        email:
          type: string
          format: email
          description: E-mail do cliente (obrigatório)
          example: joao@exemplo.com.br
        gender:
          type: string
          description: Gênero do cliente (opcional)
          enum:
            - Male
            - Female
            - Other
            - Undefined
          example: Male
        birthdate:
          type: string
          format: date
          description: Data de nascimento no formato YYYY-MM-DD (opcional)
          example: '1990-01-15'
        phone:
          $ref: '#/components/schemas/PhoneData'
        document:
          $ref: '#/components/schemas/DocumentData'
        address:
          $ref: '#/components/schemas/AddressData'
    PaymentData:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Método de pagamento (obrigatório)
          enum:
            - CreditCard
            - PIX
          example: CreditCard
        pix_expiration:
          type: integer
          description: Tempo de expiração do PIX em segundos (opcional, mín. 1)
          minimum: 1
          example: 3600
        card:
          $ref: '#/components/schemas/CardData'
    ItemData:
      type: object
      required:
        - id
        - description
        - amount
        - quantity
      properties:
        id:
          type: string
          description: Referência externa do item (obrigatório)
          example: produto_001
        description:
          type: string
          description: Descrição do item (obrigatório, máx. 255 caracteres)
          maxLength: 255
          example: Camiseta Premium
        amount:
          type: number
          format: float
          description: >-
            Valor unitário do item (obrigatório). Para testes em PIX, valores
            acima de R$ 300,00 pode resultar em erro.
          example: 99.9
        quantity:
          type: integer
          description: Quantidade do item (obrigatório)
          minimum: 1
          example: 2
    ChargeConsultData:
      type: object
      description: Dados completos de uma cobrança retornados pelo ConsultCharge
      properties:
        charge_id:
          type: string
          format: uuid
          description: ID interno da cobrança
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        charge_created_at:
          type: string
          description: Data de criação da cobrança (formatada)
          example: 11/03/2026 10:00:00
        account_id:
          type: integer
          description: ID interno da conta
          example: 1
        code:
          type: string
          description: Código da compra (purchase code)
          example: pur_abc123xyz
        value:
          type: number
          format: float
          description: Valor total da compra
          example: 199.8
        charge_value:
          type: number
          format: float
          description: Valor da cobrança
          example: 199.8
        coin:
          type: string
          description: Moeda da transação
          example: BRL
        status:
          type: string
          description: Status da compra
          enum:
            - Pending
            - Challenged
            - Approved
            - Declined
            - Refunded
            - Canceled
          example: Approved
        client:
          $ref: '#/components/schemas/ChargeClientData'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ChargeOrderData'
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            client.email:
              - O campo client.email é obrigatório.
            payment.type:
              - O campo payment.type é obrigatório.
    PhoneData:
      type: object
      required:
        - ddi
        - ddd
        - number
      properties:
        ddi:
          type: string
          description: Código do país (DDI) — obrigatório
          example: '55'
        ddd:
          type: string
          description: Código de área (DDD) — obrigatório
          example: '11'
        number:
          type: string
          description: Número do telefone sem DDD — obrigatório
          example: '999999999'
    DocumentData:
      type: object
      properties:
        type:
          type: string
          description: >-
            Tipo do documento (opcional para checkout, obrigatório para
            assinaturas)
          enum:
            - CPF
            - CNPJ
            - passport
            - undefined
          example: CPF
        number:
          type: string
          description: >-
            Número do documento (opcional para checkout, obrigatório para
            assinaturas)
          example: 123.456.789-09
    AddressData:
      type: object
      description: Endereço do cliente (obrigatório se o objeto address for enviado)
      properties:
        zipcode:
          type: string
          description: CEP (obrigatório quando address é enviado)
          example: 01310-100
        street:
          type: string
          description: Logradouro (obrigatório quando address é enviado)
          example: Avenida Paulista
        number:
          type: integer
          description: Número do endereço (obrigatório quando address é enviado)
          example: 1000
        neighborhood:
          type: string
          description: Bairro (obrigatório quando address é enviado, máx. 255 caracteres)
          example: Bela Vista
        complement:
          type: string
          description: >-
            Complemento (obrigatório quando address é enviado, máx. 255
            caracteres)
          example: Apto 42
        city:
          type: string
          description: Cidade (obrigatório quando address é enviado, máx. 255 caracteres)
          example: São Paulo
        state:
          type: string
          description: UF com 2 letras (obrigatório quando address é enviado)
          maxLength: 2
          example: SP
        country:
          type: string
          description: País (opcional, máx. 255 caracteres)
          example: Brasil
    CardData:
      type: object
      properties:
        number:
          type: string
          description: Número do cartão (obrigatório, mín. 13 dígitos)
          example: '4111111111111111'
        name:
          type: string
          description: Nome impresso no cartão (obrigatório)
          example: JOAO SILVA
        month:
          type: string
          description: Mês de validade MM (obrigatório)
          example: '12'
        year:
          type: string
          description: Ano de validade YY (obrigatório)
          example: '27'
        security_code:
          type: string
          description: Código de segurança CVV (obrigatório)
          example: '123'
        installments:
          type: integer
          description: Número de parcelas (obrigatório, mín. 1)
          minimum: 1
          example: 1
        soft_descriptor:
          type: string
          nullable: true
          description: >-
            Descrição que aparecerá na fatura do cartão (opcional, 3-50
            caracteres)
          minLength: 3
          maxLength: 50
          example: MINHA LOJA
    ChargeClientData:
      type: object
      description: Dados do cliente associado à cobrança
      properties:
        code:
          type: string
          description: Código do cliente
          example: cli_abc123
        name:
          type: string
          description: Nome do cliente
          example: João Silva
        email:
          type: string
          format: email
          description: E-mail do cliente
          example: joao@exemplo.com.br
        documents:
          type: array
          description: Documentos do cliente (filtrado pelo documento padrão)
          items:
            type: object
            properties:
              type:
                type: string
                example: CPF
              number:
                type: string
                example: 123.456.789-09
              default:
                type: boolean
                example: true
        phone:
          type: array
          description: Telefones do cliente (filtrado pelo telefone padrão)
          items:
            type: object
            properties:
              ddi:
                type: string
                example: '55'
              ddd:
                type: string
                example: '11'
              number:
                type: string
                example: '999999999'
              default:
                type: boolean
                example: true
        addresss:
          type: array
          description: Endereços do cliente (filtrado pelo endereço padrão)
          items:
            type: object
            properties:
              zipcode:
                type: string
                example: 01310-100
              street:
                type: string
                example: Avenida Paulista
              number:
                type: string
                example: '1000'
              neighborhood:
                type: string
                example: Bela Vista
              city:
                type: string
                example: São Paulo
              state:
                type: string
                example: SP
    ChargeOrderData:
      type: object
      description: Dados do pedido associado à cobrança
      properties:
        code:
          type: string
          description: Código do pedido
          example: ord_abc123xyz
        status:
          type: string
          description: Status do pedido
          enum:
            - Pending
            - Challenged
            - Approved
            - Declined
            - Refunded
            - Canceled
          example: Approved
        value:
          type: number
          format: float
          description: Valor do pedido
          example: 199.8
        error_message:
          type: string
          nullable: true
          description: Mensagem de erro do gateway (null se não houver)
          example: null
        items:
          type: array
          description: Itens do pedido
          items:
            type: object
            properties:
              code:
                type: string
                description: Código do item
                example: produto_001
              name:
                type: string
                description: Nome do item
                example: Camiseta Premium
              unitary_value:
                type: number
                format: float
                description: Valor unitário do item
                example: 99.9
              quantity:
                type: integer
                description: Quantidade
                example: 2
        charges:
          type: array
          description: Cobranças associadas ao pedido
          items:
            $ref: '#/components/schemas/ChargeDetailData'
        confirmation_codes:
          type: array
          description: >-
            Códigos de confirmação pendentes (para pedidos com status
            Challenged)
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                example: conf_xyz789
              type:
                type: string
                example: OTP
              status:
                type: string
                example: Pending
              expires_at:
                type: string
                format: date-time
                example: '2026-03-11T10:15:00.000000Z'
    ChargeDetailData:
      type: object
      description: Dados detalhados de uma cobrança dentro de um pedido
      properties:
        code:
          type: string
          description: Código da cobrança
          example: chg_abc123
        status:
          type: string
          description: Status da cobrança
          enum:
            - Pending
            - Challenged
            - Approved
            - Declined
            - Refunded
            - Canceled
          example: Approved
        value:
          type: number
          format: float
          description: Valor cobrado
          example: 199.8
        canceled_amount:
          type: number
          format: float
          nullable: true
          description: Valor já estornado
          example: 0
        nsu:
          type: string
          nullable: true
          description: NSU (Número Sequencial Único) da transação
          example: '123456789'
        installments:
          type: integer
          description: Número de parcelas
          example: 1
        attempts:
          type: integer
          description: Número de tentativas de cobrança
          example: 1
        payment:
          type: object
          description: Dados do pagamento
          properties:
            code:
              type: string
              nullable: true
              description: Código do pagamento (ex. código PIX)
              example: null
            copy_paste:
              type: string
              nullable: true
              description: Código copia e cola do PIX
              example: null
            expiration:
              type: string
              nullable: true
              description: Data/hora de expiração do pagamento
              example: null
            payment_type:
              type: string
              description: Tipo de pagamento utilizado
              enum:
                - CreditCard
                - PIX
              example: CreditCard
            installments:
              type: integer
              description: Número de parcelas
              example: 1
        last_transaction:
          type: object
          nullable: true
          description: Dados da última transação no gateway
          properties:
            transaction_id:
              type: string
              example: txn_abc123
            type:
              type: string
              example: Authorization
            status_code:
              type: string
              example: '00'
            nsu:
              type: string
              example: '123456789'
            tid:
              type: string
              example: tid_abc123
            event_date:
              type: string
              format: date-time
              example: '2026-03-11T10:00:00.000000Z'
            order_code:
              type: string
              example: ord_abc123xyz
            message_acquisition:
              type: string
              example: Transação autorizada
            return_code:
              type: string
              example: '00'
            return_message:
              type: string
              example: Sucesso
            amount:
              type: number
              nullable: true
              example: 19980
        historics:
          type: array
          description: Histórico de transações da cobrança
          items:
            type: object
            properties:
              transaction_id:
                type: string
              type:
                type: string
              status_code:
                type: string
              nsu:
                type: string
              tid:
                type: string
              event_date:
                type: string
                format: date-time
              order_code:
                type: string
              message_acquisition:
                type: string
              return_code:
                type: string
              return_message:
                type: string
              operation_type:
                type: string
              amount:
                type: number
                nullable: true
        card:
          type: object
          nullable: true
          description: Dados do cartão utilizado (mascarado)
          properties:
            id:
              type: string
              format: uuid
              example: card_abc123
            name:
              type: string
              description: Nome no cartão
              example: JOAO SILVA
            type:
              type: string
              description: Tipo do cartão
              example: credit
            number:
              type: string
              description: Número mascarado do cartão
              example: 411111****1111
            flag:
              type: string
              description: Bandeira do cartão
              example: visa
  responses:
    Unauthorized:
      description: Não autorizado — token inválido ou ausente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Unauthenticated.
            erro: true
            mensagenserro: []
            codigoretorno: 401
            id: 00000000-0000-0000-0000-000000000000
            data: []
    ValidationError:
      description: Erro de validação dos dados enviados
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          example:
            message: The given data was invalid.
            errors:
              client.email:
                - O campo client.email é obrigatório.
    ServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Um erro aconteceu.
            erro: true
            mensagenserro:
              - Erro interno. Tente novamente mais tarde.
            codigoretorno: 500
            id: 00000000-0000-0000-0000-000000000000
            data: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
        Bearer <token>`.

````