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

# Atualizar método de pagamento

> Atualiza o método de pagamento de uma assinatura.

Atualiza o método de pagamento padrão da assinatura.

Permitido quando a assinatura está em `TRIAL`, `PENDING`, `ACTIVE` ou `PAST_DUE`.

Se a assinatura estiver `PAST_DUE` e houver fatura em aberto (`OPEN`), a atualização com **cartão** dispara uma nova tentativa de cobrança dessa fatura. Em `ACTIVE`, `TRIAL` ou `PENDING`, ou ao definir **PIX**, apenas o método padrão é atualizado — a cobrança segue o ciclo da fatura.


## OpenAPI

````yaml POST /v1/subscriptions/{subscriptionId}/payment-method
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/subscriptions/{subscriptionId}/payment-method:
    post:
      tags:
        - Assinaturas
      summary: Atualizar método de pagamento
      description: >-
        Atualiza o método de pagamento padrão da assinatura (TRIAL, PENDING,
        ACTIVE ou PAST_DUE). Em PAST_DUE com fatura OPEN, atualização com cartão
        dispara nova tentativa de cobrança dessa fatura. Em
        ACTIVE/TRIAL/PENDING, ou ao definir PIX, apenas o método padrão é
        atualizado.
      operationId: updateSubscriptionPaymentMethod
      parameters:
        - name: client-id
          in: header
          description: ID público da credencial do merchant
          required: true
          schema:
            type: string
        - name: client-secret
          in: header
          description: Secret da credencial do merchant
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionPaymentMethodDto'
      responses:
        '200':
          description: Método atualizado
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateSubscriptionPaymentMethodResponseDto
        '400':
          description: Dados inválidos
        '401':
          description: Credenciais inválidas ou ausentes
        '403':
          description: Produto `recurrency` não habilitado para o merchant
        '404':
          description: Assinatura não encontrada
        '409':
          description: Método de pagamento não permitido (PAYMENT_METHOD_NOT_ALLOWED)
        '422':
          description: >-
            Status da assinatura não permite troca de método de pagamento
            (INVALID_STATUS)
components:
  schemas:
    UpdateSubscriptionPaymentMethodDto:
      type: object
      required:
        - payment_methods
      properties:
        payment_methods:
          allOf:
            - $ref: '#/components/schemas/RecurrencyPaymentMethodDto'
          description: Novo método de pagamento (credit_card ou pix) a definir como padrão.
    UpdateSubscriptionPaymentMethodResponseDto:
      type: object
      properties:
        subscription_id:
          type: string
          format: uuid
          description: Identificador da assinatura.
        payment_method:
          $ref: '#/components/schemas/SubscriptionPaymentMethodSummaryDto'
          description: Novo método de pagamento padrão.
    RecurrencyPaymentMethodDto:
      oneOf:
        - $ref: '#/components/schemas/RecurrencyCardPaymentMethodDto'
        - $ref: '#/components/schemas/RecurrencyPixPaymentMethodDto'
      discriminator:
        propertyName: type
        mapping:
          credit_card:
            $ref: '#/components/schemas/RecurrencyCardPaymentMethodDto'
          pix:
            $ref: '#/components/schemas/RecurrencyPixPaymentMethodDto'
    SubscriptionPaymentMethodSummaryDto:
      oneOf:
        - type: object
          required:
            - type
            - id
            - last_four
            - first_six
          properties:
            type:
              type: string
              enum:
                - card
              description: Método de pagamento cartão.
            id:
              type: string
              format: uuid
              description: Identificador do método de pagamento.
            last_four:
              type: string
              example: '1111'
              description: Últimos 4 dígitos do cartão.
            first_six:
              type: string
              example: '411111'
              description: Primeiros 6 dígitos (BIN) do cartão.
        - type: object
          required:
            - type
            - id
          properties:
            type:
              type: string
              enum:
                - pix
              description: Método de pagamento PIX.
            id:
              type: string
              format: uuid
              description: Identificador do método de pagamento.
    RecurrencyCardPaymentMethodDto:
      type: object
      required:
        - number
        - holder_name
        - security_code
        - expiration_month
        - expiration_year
        - type
      properties:
        number:
          type: string
          description: PAN do cartão (somente backend/PCI)
          example: '4111111111111111'
        holder_name:
          type: string
          example: JOAO DA SILVA
          description: Nome do portador impresso no cartão.
        security_code:
          type: string
          example: '123'
          description: Código de segurança (CVV). Enviado apenas do backend (PCI).
        expiration_month:
          type: integer
          minimum: 1
          maximum: 12
          example: 12
          description: Mês de expiração do cartão (1-12).
        expiration_year:
          type: integer
          example: 2030
          description: Ano de expiração do cartão (4 dígitos).
        main_payment_method:
          type: boolean
          example: true
          description: Define este cartão como método de pagamento padrão da assinatura.
        type:
          type: string
          enum:
            - credit_card
          description: Tipo do método de pagamento credit_card.
    RecurrencyPixPaymentMethodDto:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - pix
          description: Tipo do método de pagamento pix.
        main_payment_method:
          type: boolean
          example: true
          description: Define este PIX como método de pagamento padrão da assinatura.
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````