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

# Iniciar assinatura

> Faz a 1ª cobrança no cartão e cria a assinatura. A partir daí a recorrência é gerenciada pela Ephra. Não envie `amountInCents` — o valor vem da oferta/plano. A assinatura só nasce se a 1ª cobrança for aprovada; se `data.subscription` não vier na resposta, a cobrança foi recusada (veja `data.transaction.refuseReason`).

Faz a 1ª cobrança no cartão e cria a assinatura. A partir daí a **recorrência é gerenciada pela Ephra** — você não guarda o cartão nem agenda cobranças.

<Warning>
  Não envie `amountInCents`: o valor vem da oferta/plano. A assinatura só nasce se a 1ª cobrança for aprovada — se `data.subscription` não vier na resposta, a cobrança foi recusada (veja `data.transaction.refuseReason`).
</Warning>

<Note>
  Envie o header `Idempotency-Key` (UUID) para evitar cobrança duplicada em retries.
</Note>

<Info>
  Pré-requisitos, ciclo de vida e status em [Guias › Assinaturas](/guias/assinaturas). O `cardToken` (`ct_...`) vem de [Tokenizar cartão](/api-reference/cartao-token).
</Info>


## OpenAPI

````yaml POST /v1/subscriptions
openapi: 3.0.3
info:
  title: API Ephra
  description: >-
    API REST para gerar cobranças (PIX, cartão e boleto), consultar transações e
    gerenciar webhooks.
  version: 1.0.0
servers:
  - url: https://api.ephra.io
    description: Servidor de produção
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Login e obtenção do token de acesso
  - name: Pagamentos
    description: Criação de cobranças PIX, cartão e boleto
  - name: Assinaturas
    description: Cobrança recorrente — iniciar, listar, consultar e cancelar assinaturas
  - name: Transações
    description: Consulta de transações
  - name: Webhooks
    description: Cadastro e gerenciamento de webhooks
paths:
  /v1/subscriptions:
    post:
      tags:
        - Assinaturas
      summary: Iniciar assinatura
      description: >-
        Faz a 1ª cobrança no cartão e cria a assinatura. A partir daí a
        recorrência é gerenciada pela Ephra. Não envie `amountInCents` — o valor
        vem da oferta/plano. A assinatura só nasce se a 1ª cobrança for
        aprovada; se `data.subscription` não vier na resposta, a cobrança foi
        recusada (veja `data.transaction.refuseReason`).
      operationId: createSubscription
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: Evita cobrança duplicada em retries.
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreateRequest'
      responses:
        '200':
          description: >-
            Requisição processada. A 1ª cobrança pode ser aprovada (assinatura
            criada) ou recusada (assinatura não iniciada).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCreateResponse'
              examples:
                aprovada:
                  summary: 1ª cobrança aprovada (assinatura criada)
                  value:
                    success: true
                    message: Assinatura criada com sucesso
                    data:
                      transaction:
                        id: clx_tx_123
                        status: paid
                        card:
                          token: ct_...
                          brand: visa
                          last4: '1111'
                        fees: 349
                      subscription:
                        id: clx_sub_123
                        status: active
                        nextChargeAt: '2026-08-11T12:00:00.000Z'
                recusada:
                  summary: 1ª cobrança recusada (assinatura não iniciada)
                  value:
                    success: true
                    message: Primeira cobrança não aprovada — assinatura não iniciada
                    data:
                      transaction:
                        id: clx_tx_124
                        status: refused
                        card:
                          token: ct_...
                          brand: visa
                          last4: '1111'
                        fees: 0
                        refuseReason: INSUFFICIENT_FUNDS
        '400':
          description: >-
            A oferta não é um plano de assinatura, ou não pertence ao
            produto/empresa.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: >-
                  Este produto não é uma assinatura. Configure-o como assinatura
                  (digital + recorrente) no dashboard.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    SubscriptionCreateRequest:
      type: object
      required:
        - productId
        - offerSlug
        - card
        - customer
      properties:
        productId:
          type: string
          description: ID do produto de assinatura
          example: prod_ABC123
        offerSlug:
          type: string
          description: Slug do plano (oferta de assinatura)
          example: plano-mensal-premium
        card:
          type: object
          required:
            - cardToken
          properties:
            cardToken:
              type: string
              description: Token ct_... gerado em /v1/card-token
              example: ct_9f8a7b...
            holderName:
              type: string
              description: Nome impresso no cartão
              example: MARIA SILVA
        customer:
          $ref: '#/components/schemas/Customer'
        orderBumpIds:
          type: array
          items:
            type: string
          description: IDs de order bumps da 1ª compra
        couponTag:
          type: string
          description: Cupom de desconto
        postbackUrl:
          type: string
          format: uri
          description: Recebe o postback desta transação
        description:
          type: string
          description: Descrição livre
    SubscriptionCreateResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Assinatura criada com sucesso
        data:
          type: object
          properties:
            transaction:
              type: object
              properties:
                id:
                  type: string
                  example: clx_tx_123
                status:
                  type: string
                  enum:
                    - paid
                    - refused
                  example: paid
                card:
                  type: object
                  properties:
                    token:
                      type: string
                      example: ct_...
                    brand:
                      type: string
                      example: visa
                    last4:
                      type: string
                      example: '1111'
                fees:
                  type: integer
                  example: 349
                refuseReason:
                  type: string
                  nullable: true
                  description: Presente apenas quando `status` é `refused`.
                  enum:
                    - INSUFFICIENT_FUNDS
                    - CARD_BLOCKED
                    - INVALID_DATA
                    - TIMEOUT
                    - EXPIRED_CARD
                    - ANTIFRAUD_REJECTED
                    - OTHER
            subscription:
              type: object
              description: Presente apenas se a 1ª cobrança for aprovada.
              properties:
                id:
                  type: string
                  example: clx_sub_123
                status:
                  type: string
                  example: active
                nextChargeAt:
                  type: string
                  example: '2026-08-11T12:00:00.000Z'
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Mensagem descritiva do erro
    Customer:
      type: object
      required:
        - documentType
        - document
      properties:
        documentType:
          type: string
          enum:
            - cpf
            - cnpj
          example: cpf
        document:
          type: string
          description: CPF/CNPJ do pagador (validado)
          example: '12345678909'
        name:
          type: string
          example: Maria Silva
        email:
          type: string
          format: email
          example: maria@email.com
        phone:
          type: string
          example: '+5511999998888'
        billingAddress:
          $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        street:
          type: string
        number:
          type: string
        neighborhood:
          type: string
        city:
          type: string
        state:
          type: string
        zipCode:
          type: string
  responses:
    Unauthorized:
      description: Token ausente, inválido ou expirado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            error: Unauthorized
            message: Token inválido ou expirado
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````