> ## 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.

# Consultar pagamento

> Consulta o status e detalhes de um pagamento pelo ID.



## OpenAPI

````yaml GET /v1/payments/{id}
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/{id}:
    get:
      tags:
        - Pagamentos
      summary: Consultar pagamento
      description: Consulta o status e detalhes de um pagamento pelo ID.
      operationId: getPayment
      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
        - name: id
          required: true
          in: path
          description: ID único da transação
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Dados do pagamento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponseDto'
        '401':
          description: Credenciais inválidas ou ausentes
        '404':
          description: Pagamento não encontrado
components:
  schemas:
    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
    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
    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

````