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

# Gerar cobranca

Cria uma cobranca de entrada e retorna o `transactionId` publico.

<Info>
  Para PIX, a resposta inclui `pixCode`.
  Para cartao, a resposta inclui `checkout`.
  Se quiser atribuicao de campanha, envie `tracking_parameters` com seus UTMs.
</Info>

<Info>
  Se voce estiver implementando checkout de cartao, veja tambem a pagina [Cartao](/card-checkout).
</Info>


## OpenAPI

````yaml POST /v1/integrations/create-transaction
openapi: 3.0.3
info:
  title: AXNPAY Integrations API
  version: '2026-05-02'
  description: >-
    Referencia publica para integracao de cobrancas, saques, conciliacao e
    checkout de cartao da AXNPAY.
servers:
  - url: https://api.axnpay.com.br
security:
  - secretKeyAuth: []
paths:
  /v1/integrations/create-transaction:
    post:
      tags:
        - Integrations
      summary: Gerar cobranca
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransactionRequest'
            example:
              amount: 150
              currency: brl
              productName: 'Pedido #1001'
              description: Plano Premium
              clientName: Maria
              clientEmail: maria@example.com
              referenceId: 9e4a5fb4-61bb-4b38-9bb6-b7029b74bdf6
              checkoutUiMode: hosted
              paymentMethodTypes:
                - card
                - link
              successUrl: https://merchant.example.com/checkout/success
              cancelUrl: https://merchant.example.com/checkout/cancel
              tracking_parameters:
                utm_source: google
                utm_medium: cpc
                utm_campaign: launch
      responses:
        '201':
          description: Cobranca criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTransactionResponse'
              example:
                transactionId: 9e4a5fb4-61bb-4b38-9bb6-b7029b74bdf6
                status: PENDING
                type: CASHIN
                source: CREDIT_CARD
                origin: API
                amount: 150
                feeAmount: 0
                finalAmount: 150
                description: Plano Premium
                productName: 'Pedido #1001'
                trackingParameters:
                  utm_source: google
                  utm_medium: cpc
                  utm_campaign: launch
                pixCode: null
                pixKeyType: null
                pixKey: null
                clientName: Maria
                clientEmail: maria@example.com
                clientPhone: null
                clientCpf: null
                externalId: checkout_sess_abc123
                gatewayId: null
                endToEndId: null
                receiptUrl: null
                transactionDate: '2026-05-02T18:46:16.748Z'
                paidAt: null
                createdAt: '2026-05-02T18:46:16.748Z'
                updatedAt: '2026-05-02T18:46:16.748Z'
                balanceImpact: true
                settlementMode: internal
                checkout:
                  sessionId: checkout_sess_abc123
                  uiMode: hosted
                  url: https://checkout.axnpay.com/session/checkout_sess_abc123
                  clientSecret: null
                  publishableKey: null
                  accountDisplayName: AXON SERVICOS FINANCEIROS LTDA
                  paymentMethodConfigurationId: null
                  requestedPaymentMethodTypes:
                    - card
                    - link
                  livemode: true
                  paymentStatus: unpaid
                  status: open
                  expiresAt: null
                  webhookConfigured: true
                  settlementMode: internal
                  balanceImpact: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    CreateTransactionRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          minimum: 0.01
          maximum: 1000000
          description: Valor bruto da cobranca.
        description:
          type: string
          description: Descricao livre da cobranca.
        productName:
          type: string
          description: Nome do produto ou servico.
        clientName:
          type: string
          description: Nome do pagador.
        clientEmail:
          type: string
          format: email
          description: Email do pagador.
        clientPhone:
          type: string
          description: Telefone do pagador.
        clientCpf:
          type: string
          description: Documento do pagador.
        tracking_parameters:
          $ref: '#/components/schemas/TrackingParameters'
        utm_source:
          type: string
        utm_medium:
          type: string
        utm_campaign:
          type: string
        utm_content:
          type: string
        utm_term:
          type: string
        referenceId:
          type: string
          format: uuid
          description: Chave de idempotencia do merchant.
        paymentMethod:
          type: string
          description: 'Exemplo: credit_card, visa, master, bolbradesco.'
        paymentMethodTypes:
          type: array
          items:
            type: string
          description: >-
            Usado quando o checkout web de cartao ativo suportar selecao de
            metodos no frontend. Exemplo: ["card"], ["card","link"], ["paypal"].
        cardToken:
          type: string
          description: Token de cartao usado em fluxos Mercado Pago.
        installments:
          type: integer
          minimum: 1
          maximum: 12
        currency:
          type: string
          description: >-
            Moeda ISO-4217. Default: brl. A disponibilidade dos metodos depende
            do checkout ativo na conta.
        pixKeyType:
          $ref: '#/components/schemas/PixKeyType'
        pixKey:
          type: string
        checkoutUiMode:
          $ref: '#/components/schemas/CheckoutUiMode'
        successUrl:
          type: string
          format: uri
        cancelUrl:
          type: string
          format: uri
        returnUrl:
          type: string
          format: uri
    CreateTransactionResponse:
      allOf:
        - $ref: '#/components/schemas/TransactionPublic'
        - type: object
          properties:
            checkout:
              $ref: '#/components/schemas/CheckoutSession'
    TrackingParameters:
      type: object
      nullable: true
      additionalProperties: false
      properties:
        utm_source:
          type: string
        utm_medium:
          type: string
        utm_campaign:
          type: string
        utm_content:
          type: string
        utm_term:
          type: string
    PixKeyType:
      type: string
      enum:
        - CPF
        - CNPJ
        - EMAIL
        - PHONE
        - EVP
    CheckoutUiMode:
      type: string
      enum:
        - hosted
        - embedded
        - custom
    TransactionPublic:
      type: object
      properties:
        transactionId:
          type: string
          nullable: true
          format: uuid
        status:
          $ref: '#/components/schemas/TxStatus'
        type:
          $ref: '#/components/schemas/TxType'
        source:
          type: string
        origin:
          $ref: '#/components/schemas/TxOrigin'
        amount:
          type: number
        feeAmount:
          type: number
        finalAmount:
          type: number
        description:
          type: string
          nullable: true
        productName:
          type: string
          nullable: true
        trackingParameters:
          $ref: '#/components/schemas/TrackingParameters'
        pixCode:
          type: string
          nullable: true
        pixKeyType:
          allOf:
            - $ref: '#/components/schemas/PixKeyType'
          nullable: true
        pixKey:
          type: string
          nullable: true
        clientName:
          type: string
          nullable: true
        clientEmail:
          type: string
          nullable: true
        clientPhone:
          type: string
          nullable: true
        clientCpf:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        gatewayId:
          type: string
          nullable: true
        endToEndId:
          type: string
          nullable: true
        receiptUrl:
          type: string
          nullable: true
        transactionDate:
          type: string
          format: date-time
          nullable: true
        paidAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        balanceImpact:
          type: boolean
        settlementMode:
          type: string
    CheckoutSession:
      type: object
      nullable: true
      properties:
        sessionId:
          type: string
        uiMode:
          $ref: '#/components/schemas/CheckoutUiMode'
        url:
          type: string
          nullable: true
        clientSecret:
          type: string
          nullable: true
        publishableKey:
          type: string
          nullable: true
        accountDisplayName:
          type: string
          nullable: true
        paymentMethodConfigurationId:
          type: string
          nullable: true
        requestedPaymentMethodTypes:
          type: array
          nullable: true
          items:
            type: string
        livemode:
          type: boolean
        paymentStatus:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        webhookConfigured:
          type: boolean
        settlementMode:
          type: string
        balanceImpact:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          type: string
        message:
          type: string
        detail:
          type: object
          additionalProperties: true
      required:
        - statusCode
        - error
        - message
    TxStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - COMPLETED
        - FAILED
        - REVERSED
        - CANCELLED
        - CHARGEBACK
    TxType:
      type: string
      enum:
        - CASHIN
        - CASHOUT
        - INFRACTION
    TxOrigin:
      type: string
      enum:
        - API
        - PAINEL
        - APP
  responses:
    BadRequest:
      description: Requisicao invalida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Nao autenticado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Operacao nao permitida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Conflito de idempotencia
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Servico indisponivel ou ambiente nao configurado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    secretKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_live_prod_*
      description: 'Use sua secret key: Bearer sk_live_prod_...'

````