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

# Processar Pagamento

> Processa o pagamento de débitos veiculares com cartão tokenizado

## Descrição

Processa o pagamento de débitos veiculares utilizando um cartão tokenizado. Este é o último passo do fluxo de pagamento.

<Warning>
  **Antifraude Integrado**: Todos os pagamentos passam pelo sistema antifraude da Uvvipague antes de serem aprovados.
</Warning>

## Pré-requisitos

Antes de processar o pagamento, você deve:

1. Ter criado um checkout válido (`checkoutId`)
2. Ter tokenizado o cartão do cliente (`cardToken`)
3. Ter simulado as parcelas (opcional, mas recomendado)

## Status de Pagamento

O pagamento pode retornar os seguintes status:

* **paid**: Pagamento aprovado e processado com sucesso
* **in\_analysis**: Transação em análise pelo antifraude (aguardar webhook)
* **refused**: Transação recusada pela operadora ou antifraude
* **processing**: Transação sendo processada
* **awaiting\_payment**: Aguardando confirmação de pagamento
* **cancelled**: Pagamento cancelado
* **refunded**: Pagamento estornado
* **chargeback**: Contestação de pagamento

<Note>
  Consulte a [documentação de ENUMs](/enums-tipos#payment-status) para detalhes completos sobre cada status.
</Note>

## Webhooks

Após o processamento, você receberá webhooks sobre:

* Confirmação do pagamento
* Atualização de status
* Liquidação dos débitos nos órgãos

<Info>
  Configure seus webhooks na [documentação de webhooks](/webhooks) para receber notificações automáticas.
</Info>

## Códigos de Resposta HTTP

### 200 - Sucesso

Pagamento processado com sucesso. Verifique o campo `status` para o resultado.

### 400 - Bad Request

Dados inválidos ou incompletos na requisição.

### 402 - Payment Required

Pagamento recusado pela operadora. Possíveis motivos:

* `PAYMENT_REJECTED`: Recusado pela operadora
* `INVALID_CARD`: Cartão inválido
* `INSUFFICIENT_FUNDS`: Saldo insuficiente
* `FRAUD_DETECTED`: Fraude detectada
* `CARD_EXPIRED`: Cartão expirado
* `INVALID_CVV`: CVV inválido

### 422 - Unprocessable Entity

Dados válidos mas não podem ser processados (ex: checkout expirado).

## Segurança

* Nunca armazene dados completos de cartão
* Use sempre tokenização
* Valide o CVV em cada transação
* Implemente 3DS quando disponível


## OpenAPI

````yaml POST /uvvi/v1/payment
openapi: 3.1.0
info:
  title: Uvvipague API
  description: >-
    API completa para consulta e pagamento de débitos veiculares em todo o
    Brasil
  version: 1.0.0
  contact:
    name: Suporte Uvvipague
    email: suporte@uvvipague.com.br
    url: https://uvvipague.com.br
servers:
  - url: https://api.uvvipague.com.br
    description: Servidor de Produção
  - url: https://api-sandbox.uvvipague.com.br
    description: Servidor de Homologação/Sandbox
security:
  - apiKey: []
tags:
  - name: Veículos
    description: Endpoints para consulta e enriquecimento de informações de veículos
  - name: Débitos
    description: Endpoints para consulta de débitos veiculares
  - name: Pagamentos
    description: Endpoints para processamento de pagamentos
  - name: Webhooks
    description: Endpoints para configuração e gerenciamento de webhooks
paths:
  /uvvi/v1/payment:
    post:
      tags:
        - Pagamentos
      summary: Efetuar Pagamento
      description: Processa o pagamento de débitos veiculares com cartão tokenizado
      operationId: processPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Pagamento processado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Requisição inválida - Dados incorretos ou incompletos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Pagamento recusado - Transação negada pela operadora ou antifraude
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '422':
          description: >-
            Entidade não processável - Dados válidos mas não podem ser
            processados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PaymentRequest:
      type: object
      required:
        - checkoutId
        - cardToken
        - installments
      properties:
        checkoutId:
          type: string
          description: ID do checkout criado
          example: chk_abc123xyz
        cardToken:
          type: string
          description: Token do cartão tokenizado
          example: tok_abc123xyz
        installments:
          type: integer
          description: Número de parcelas
          example: 3
        customer:
          type: object
          properties:
            name:
              type: string
              example: João da Silva
            email:
              type: string
              example: joao@example.com
            cpfCnpj:
              type: string
              example: '12345678900'
    PaymentResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            paymentId:
              type: string
              example: pay_abc123xyz
            status:
              type: string
              enum:
                - paid
                - in_analysis
                - refused
                - processing
                - awaiting_payment
                - cancelled
                - refunded
                - chargeback
              example: paid
              description: Status do pagamento conforme PaymentStatus enum
            amount:
              type: number
              example: 1315.89
            installments:
              type: integer
              example: 3
            transactionId:
              type: string
              example: txn_abc123xyz
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - UNAUTHORIZED
                - NOT_FOUND
                - VALIDATION_ERROR
                - RATE_LIMIT_EXCEEDED
                - SERVICE_UNAVAILABLE
              example: INVALID_REQUEST
              description: Código do erro
            message:
              type: string
              example: Parâmetros inválidos na requisição
            details:
              type: object
              description: Detalhes adicionais sobre o erro
    PaymentError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - PAYMENT_REJECTED
                - INVALID_CARD
                - INSUFFICIENT_FUNDS
                - FRAUD_DETECTED
                - CARD_EXPIRED
                - INVALID_CVV
              example: PAYMENT_REJECTED
              description: Código específico do erro de pagamento
            message:
              type: string
              example: Pagamento recusado pela operadora
            details:
              type: string
              example: Saldo insuficiente
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key fornecida no painel administrativo da Uvvipague

````