> ## Documentation Index > Fetch the complete documentation index at: https://docs.purincash.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > Cria uma assinatura recorrente via PIX vinculada a um produto ativo e retorna o código PIX (brCode) da primeira cobrança. Funciona também no modo sandbox (chaves ps_test_), com dados simulados. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/subscriptions openapi: 3.1.0 info: title: PurinCash API version: 1.0.0 servers: - url: https://api.purincash.com description: Produção security: - bearerAuth: [] tags: - name: Cartao description: Pagamentos no cartao de credito. - name: Cobrancas description: Cobrancas PIX avulsas com valor livre. - name: Entregas description: Conteudo entregue automaticamente apos o pagamento. - name: Disputas description: Contestacoes (MED) e envio de evidencias. - name: Pagamentos description: Pagamentos PIX e LTC vinculados ou nao a um produto. - name: Saques description: Saques em PIX, LTC e USDT. - name: Produtos description: Produtos de cobranca criados pela API. - name: Sandbox description: Simulacao de pagamentos e saldo de teste. - name: Splits description: Cobrancas divididas entre varias contas. - name: Loja description: Produtos da loja do Discord (somente leitura). - name: Assinaturas description: PIX recorrente. - name: Carteira description: Saldo, retencoes e valores a liberar. paths: /v1/subscriptions: post: tags: - Assinaturas summary: Create Subscription description: >- Cria uma assinatura recorrente via PIX vinculada a um produto ativo e retorna o código PIX (brCode) da primeira cobrança. Funciona também no modo sandbox (chaves ps_test_), com dados simulados. operationId: createSubscription requestBody: required: true content: application/json: schema: type: object required: - productId - customer properties: productId: type: string description: >- ID (ObjectId) de um produto ativo que define o valor e o nome da assinatura. customer: type: object required: - name description: Dados do cliente. O nome é obrigatório para assinaturas. properties: name: type: string maxLength: 100 description: Nome do cliente. Obrigatório. Máximo de 100 caracteres. externalId: type: string maxLength: 200 description: >- Identificador do cliente no seu sistema. Máximo de 200 caracteres. callbackUrl: type: string format: uri maxLength: 500 description: >- URL HTTPS pública para receber os webhooks das cobranças. Máximo de 500 caracteres. metadata: type: string maxLength: 2048 default: '{}' description: String JSON com dados livres. Máximo de 2048 caracteres. frequency: type: string enum: - WEEKLY - MONTHLY - SEMIANNUALLY - ANNUALLY default: MONTHLY description: Frequência de cobrança da assinatura. dayGenerateCharge: type: integer minimum: 4 maximum: 28 description: Dia do mês em que as cobranças são geradas (entre 4 e 28). example: productId: 65f0c2a1e4b0a1b2c3d4e5f6 customer: name: João Silva externalId: user_123 callbackUrl: https://minhaloja.com/webhooks/purincash metadata: '{"plano":"premium"}' frequency: MONTHLY dayGenerateCharge: 15 responses: '200': description: Assinatura criada com sucesso. content: application/json: schema: type: object properties: paymentId: type: string description: >- Identificador do pagamento da assinatura (prefixo psa_sub_). status: type: string description: Status da assinatura. Sempre "pending" na criação. type: type: string description: Tipo do pagamento. Sempre "subscription". subscriptionId: type: string description: Identificador da assinatura no gateway de pagamento. amountCents: type: integer description: Valor de cada cobrança em centavos, definido pelo produto. currency: type: string description: Moeda do produto (ex. "BRL"). productName: type: string description: Nome do produto vinculado à assinatura. frequency: type: string enum: - WEEKLY - MONTHLY - SEMIANNUALLY - ANNUALLY description: Frequência de cobrança aplicada. environment: type: string enum: - live - sandbox description: Ambiente em que a assinatura foi criada. pix: type: object description: Dados PIX da primeira cobrança. properties: brCode: type: - string - 'null' description: >- Código PIX copia-e-cola (BR Code) da cobrança, ou null quando não disponível. paymentLinkUrl: type: - string - 'null' description: >- Link de pagamento hospedado, ou null quando não disponível. dayGenerateCharge: type: integer description: >- Dia do mês em que as cobranças são geradas. Se não informado, usa o dia atual. example: paymentId: psa_sub_a1b2c3d4... status: pending type: subscription subscriptionId: sub_xyz... amountCents: 4990 currency: BRL productName: Premium Plan frequency: MONTHLY environment: live pix: brCode: 00020126580014br.gov.bcb.pix... paymentLinkUrl: https://pay.exemplo.com/sub_9f8e7d6c dayGenerateCharge: 15 '400': description: >- Parâmetro inválido ou ausente (ex. productId ausente ou com formato inválido, customer.name ausente, callbackUrl inválida). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: customer.name is required for subscriptions '401': description: Chave de API inválida, ausente ou revogada. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Loja não verificada. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Produto não encontrado ou inativo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Product not found or inactive '502': description: Falha no gateway de pagamento ao criar a assinatura ou a cobrança. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Gateway de pagamento não configurado. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: error: type: string description: >- Mensagem de erro legivel. Trate pelo codigo HTTP; o texto pode mudar. securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_). ````