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

# Criar pagamento

> Cria um novo pagamento (PIX, cartão de crédito ou boleto). Valores sempre em centavos.



## OpenAPI

````yaml POST /v1/payments
openapi: 3.0.0
info:
  title: UvviPay Public API
  description: >-
    Endpoints públicos da plataforma UvviPay para integração de subcontas
    (submerchants).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.uvvipay.com.br
    description: Produção
  - url: https://api-staging.uvvipay.com.br
    description: Staging
security:
  - client-id: []
    client-secret: []
tags: []
paths:
  /v1/payments:
    post:
      tags:
        - Pagamentos
      summary: Criar pagamento
      description: >-
        Cria um novo pagamento (PIX, cartão de crédito ou boleto). Valores
        sempre em centavos.
      operationId: createPayment
      parameters:
        - name: client-secret
          in: header
          description: Secret da credencial do merchant
          required: true
          schema:
            type: string
        - name: client-id
          in: header
          description: ID público da credencial do merchant
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentDto'
      responses:
        '200':
          description: Pagamento criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponseDto'
        '400':
          description: Dados inválidos
        '401':
          description: Credenciais inválidas ou ausentes
        '422':
          description: Pagamento recusado
        '500':
          description: Erro interno
components:
  schemas:
    CreatePaymentDto:
      type: object
      properties:
        externalId:
          type: string
          description: Identificador único do pedido no sistema do merchant
          example: ORDER-12345
        amount:
          type: number
          description: Valor total em centavos (mínimo 100, máximo 15000000)
          minimum: 100
          maximum: 15000000
          example: 7500
        paymentMethod:
          type: string
          enum:
            - pix
            - credit_card
            - boleto
          example: pix
        customer:
          $ref: '#/components/schemas/PaymentCustomerDto'
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PaymentItemDto'
        subMerchant:
          allOf:
            - $ref: '#/components/schemas/PaymentSubMerchantDto'
          description: >-
            Subconta owner da transação (opcional). Quando informada, é
            identificada pelo documento (CPF/CNPJ) de uma subconta já cadastrada
            e ativa e passa a ser a owner do split; sem este objeto, o próprio
            merchant é o owner.
        split:
          type: array
          minItems: 1
          description: >-
            Regras de divisão do valor líquido entre subcontas recebedoras.
            Requer os produtos PaaS e Split habilitados para o merchant; o owner
            é o próprio merchant, salvo se um subMerchant for informado. Os
            valores resolvidos retornam no campo split da resposta. Ver guia
            Pagamentos com Split.
          items:
            $ref: '#/components/schemas/PaymentSplitRuleDto'
        card:
          $ref: '#/components/schemas/PaymentCardDto'
        applePay:
          allOf:
            - $ref: '#/components/schemas/ApplePayDto'
          description: >-
            Pagamento via Apple Pay — alternativa ao bloco card (envie um ou
            outro, nunca ambos). Válido apenas com paymentMethod credit_card; o
            criptograma do token dispensa CVV e 3DS. Ver guia Apple Pay.
        threeDSData:
          $ref: '#/components/schemas/ThreeDSDataDto'
        ip:
          type: string
          example: 192.168.1.100
        invoiceDescriptor:
          type: string
          example: LOJA EXEMPLO
        fingerprint:
          type: string
        metaData:
          type: object
          additionalProperties: true
          example:
            order_id: '123'
      required:
        - externalId
        - amount
        - paymentMethod
        - customer
        - items
      not:
        required:
          - card
          - applePay
        description: >-
          card e applePay são mutuamente exclusivos — envie um ou outro, nunca
          ambos
    PaymentResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: d398b016-3c29-41b4-afc0-bbf8c81c683c
        status:
          type: string
          enum:
            - waiting_payment
            - paid
            - refused
            - refunded
            - in_analysis
          example: paid
        amount:
          type: number
          example: 15680
        paymentMethod:
          type: string
          example: credit_card
        transactionId:
          type: string
        pix:
          $ref: '#/components/schemas/PixResponseDto'
        boleto:
          $ref: '#/components/schemas/BoletoResponseDto'
        refusedReason:
          $ref: '#/components/schemas/RefusedReasonDto'
        subMerchant:
          $ref: '#/components/schemas/PaymentSubMerchantResponseDto'
        split:
          type: array
          description: >-
            Split resolvido da transação: valor efetivamente destinado a cada
            recebedor, em centavos (quando a transação possui split)
          items:
            $ref: '#/components/schemas/PaymentSplitRuleResponseDto'
        customer:
          $ref: '#/components/schemas/PaymentCustomerResponseDto'
        items:
          type: array
          items:
            $ref: '#/components/schemas/PaymentItemResponseDto'
        externalReference:
          type: string
          example: 35d29135-f14e-4695-b9ae-ccde91676a60
        createdAt:
          type: string
          format: date-time
          example: '2026-07-02T19:41:46.738Z'
      required:
        - id
        - status
        - amount
        - paymentMethod
        - createdAt
    PaymentCustomerDto:
      type: object
      properties:
        name:
          type: string
          example: João da Silva
          maxLength: 255
        email:
          type: string
          format: email
          example: joao@exemplo.com
          maxLength: 320
        phone:
          type: string
          example: '11987654321'
          maxLength: 20
        document:
          $ref: '#/components/schemas/PaymentDocumentDto'
        address:
          $ref: '#/components/schemas/PaymentAddressDto'
        externalRef:
          type: string
          example: CUSTOMER-123
      required:
        - name
        - email
        - document
    PaymentItemDto:
      type: object
      properties:
        title:
          type: string
          example: Produto X
        quantity:
          type: number
          minimum: 1
          example: 1
        unitPrice:
          type: number
          minimum: 0
          example: 7500
        tangible:
          type: boolean
          example: true
      required:
        - title
        - quantity
        - unitPrice
    PaymentSubMerchantDto:
      type: object
      description: >-
        Subconta owner da transação. Obrigatório quando split é enviado: é dela
        que sai o valor líquido distribuído aos recebedores.
      properties:
        id:
          type: string
          description: Identificador da subconta no sistema do integrador
          example: SUB-001
        legalName:
          type: string
          description: Razão social da subconta
          example: Loja Exemplo LTDA
        document:
          $ref: '#/components/schemas/PaymentDocumentDto'
        mcc:
          type: string
          description: Merchant Category Code da subconta
          example: '5732'
        url:
          type: string
          description: Site da subconta
          example: https://lojaexemplo.com.br
        phone:
          type: string
          description: Telefone da subconta
          example: '11999998888'
        address:
          $ref: '#/components/schemas/PaymentAddressDto'
        invoiceDescriptor:
          type: string
          description: Descritor exibido na fatura do portador
          example: LOJA EXEMPLO
      required:
        - id
        - legalName
        - document
        - mcc
        - url
        - phone
        - address
    PaymentSplitRuleDto:
      type: object
      description: >-
        Regra de divisão do valor líquido da transação para uma subconta
        recebedora.
      properties:
        recipientId:
          type: string
          format: uuid
          description: ID (UUID) da subconta recebedora, retornado na criação da subconta
          example: 5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f
        type:
          type: string
          enum:
            - percentage
            - flat
          description: >-
            percentage: percentual sobre o líquido (1 a 100). flat: valor fixo
            inteiro em centavos
          example: percentage
        amount:
          type: number
          minimum: 1
          description: >-
            Percentual (1 a 100) quando type=percentage, ou valor inteiro em
            centavos quando type=flat
          example: 30
      required:
        - recipientId
        - type
        - amount
    PaymentCardDto:
      type: object
      properties:
        number:
          type: string
          example: '4111111111111111'
        holderName:
          type: string
          example: JOAO DA SILVA
        cvv:
          type: string
          example: '123'
        expirationMonth:
          type: number
          minimum: 1
          maximum: 12
          example: 12
        expirationYear:
          type: number
          example: 2029
        installments:
          type: number
          minimum: 1
          maximum: 24
          example: 1
        deviceId:
          type: string
          example: device_abc123
        brand:
          type: string
          example: visa
      required:
        - number
        - holderName
        - cvv
        - expirationMonth
        - expirationYear
        - installments
    ApplePayDto:
      type: object
      properties:
        paymentData:
          type: string
          description: >-
            Base64 do PKPaymentToken.paymentData, exatamente como sai do
            PassKit/Apple Pay JS
          example: eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiLi4uIn0=
        network:
          type: string
          description: >-
            Bandeira informada pela Apple em paymentMethod.network (ex.: Visa,
            MasterCard)
          example: Visa
        installments:
          type: integer
          minimum: 1
          maximum: 24
          default: 1
          description: Número de parcelas
      required:
        - paymentData
        - network
    ThreeDSDataDto:
      type: object
      description: Dados do resultado 3DS para cobrança autenticada com cartão de crédito
      properties:
        cavv:
          type: string
          description: Cardholder Authentication Verification Value
        eci:
          type: string
          description: Electronic Commerce Indicator
          example: '05'
        xid:
          type: string
        tdsver:
          type: string
          example: 2.2.0
        tdsdsxid:
          type: string
        directoryServerTransactionId:
          type: string
        ucaf:
          type: string
        paresStatus:
          type: string
        veresEnrolled:
          type: string
        authenticationResult:
          type: string
        returnCode:
          type: string
        returnMessage:
          type: string
        version:
          type: string
        type:
          type: string
          enum:
            - frictionless
            - challenge
    PixResponseDto:
      type: object
      properties:
        qrcode:
          type: string
          description: Payload PIX (copia e cola / QR Code)
    BoletoResponseDto:
      type: object
      properties:
        url:
          type: string
          example: https://exemplo.com/boleto/abc123
        digitableLine:
          type: string
          example: 34191.79001 01043.510047 91020.150008 1 98760000012345
    RefusedReasonDto:
      type: object
      description: >-
        Motivo da recusa (presente apenas quando status = refused). Consulte o
        guia [Recusas de cartão](/recusas-de-cartao) para entender as categorias
        e como orientar o cliente.
      properties:
        category:
          type: string
          description: >-
            Categoria abstraída do motivo da recusa. Retornada na consulta do
            pagamento (GET).
          enum:
            - issuer_declined
            - invalid_card_data
            - temporary_unavailable
            - suspected_fraud
            - installments_exceeded
          example: issuer_declined
        code:
          type: string
          description: >-
            Referência técnica da recusa, retornada apenas na resposta de
            criação (POST). Valor opaco — não use para lógica de negócio.
          example: '51'
        description:
          type: string
          description: Descrição amigável do motivo, pronta para exibição.
          example: Recusa do banco emissor
    PaymentSubMerchantResponseDto:
      type: object
      description: Dados públicos do submerchant (owner) vinculado à transação.
      properties:
        internalId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        legalName:
          type: string
          description: Razão social / nome do titular do submerchant
          example: Loja do João LTDA
        documentType:
          type: string
          enum:
            - cpf
            - cnpj
          example: cnpj
        documentNumber:
          type: string
          example: '12345678000199'
    PaymentSplitRuleResponseDto:
      type: object
      description: Valor do split efetivamente destinado a um recebedor.
      properties:
        recipient_id:
          type: string
          format: uuid
          description: Identificador público (UUID) do recebedor do split
          example: 5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f
        amount:
          type: number
          description: Valor creditado ao recebedor, em centavos
          example: 2500
      required:
        - recipient_id
        - amount
    PaymentCustomerResponseDto:
      type: object
      description: Dados completos do cliente (presente quando disponível).
      properties:
        name:
          type: string
          example: Gustavo Marin
        email:
          type: string
          example: gustavomarin616@hotmail.com
        phone:
          type: string
          example: '55996299418'
        documentNumber:
          type: string
          example: '77042506049'
        documentType:
          type: string
          enum:
            - cpf
            - cnpj
            - passport
          example: cpf
        address:
          $ref: '#/components/schemas/PaymentCustomerAddressResponseDto'
    PaymentItemResponseDto:
      type: object
      description: Item da transação, retornado exatamente como salvo na criação.
      properties:
        title:
          type: string
          example: Produto X
        quantity:
          type: number
          example: 1
        tangible:
          type: boolean
          example: true
        unitPrice:
          type: number
          example: 15680
    PaymentDocumentDto:
      type: object
      properties:
        number:
          type: string
          example: '12345678901'
          maxLength: 50
        type:
          type: string
          enum:
            - cpf
            - cnpj
          example: cpf
      required:
        - number
        - type
    PaymentAddressDto:
      type: object
      properties:
        zipCode:
          type: string
          example: '01310100'
          maxLength: 20
        street:
          type: string
          example: Avenida Paulista
          maxLength: 255
        streetNumber:
          type: string
          example: '1000'
          maxLength: 50
        complement:
          type: string
          example: Conjunto 101
        neighborhood:
          type: string
          example: Bela Vista
          maxLength: 100
        city:
          type: string
          example: São Paulo
          maxLength: 100
        state:
          type: string
          example: SP
          maxLength: 21
        country:
          type: string
          example: BR
          maxLength: 2
      required:
        - zipCode
        - street
        - streetNumber
        - neighborhood
        - city
        - state
        - country
    PaymentCustomerAddressResponseDto:
      type: object
      properties:
        zipCode:
          type: string
          example: '98300000'
        street:
          type: string
          example: Major Novais
        streetNumber:
          type: string
          example: '444'
        neighborhood:
          type: string
          example: Centro
        city:
          type: string
          example: Palmeira das Missões
        state:
          type: string
          example: RS
        country:
          type: string
          example: BR
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````