> ## Documentation Index > Fetch the complete documentation index at: https://docs.purin.cash/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > Cria uma assinatura por Pix Automático (o padrão de recorrência do Banco Central) vinculada a um produto ativo. O brCode devolvido é um QR composto: o cliente paga o primeiro ciclo e, no mesmo ato, autoriza os próximos no app do banco. A partir daí cada renovação é cobrada sozinha, um período depois do primeiro pagamento, e chega como um payment.paid com subscriptionId e subscriptionCycle. A autorização é presa ao CPF ou CNPJ do titular da conta que paga (customer.taxId). 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.purin.cash 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: Subcontas description: Ledger de saldo por cliente do integrador. - 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 por Pix Automático (o padrão de recorrência do Banco Central) vinculada a um produto ativo. O brCode devolvido é um QR composto: o cliente paga o primeiro ciclo e, no mesmo ato, autoriza os próximos no app do banco. A partir daí cada renovação é cobrada sozinha, um período depois do primeiro pagamento, e chega como um payment.paid com subscriptionId e subscriptionCycle. A autorização é presa ao CPF ou CNPJ do titular da conta que paga (customer.taxId). 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 - taxId description: >- Dados do titular da conta que vai pagar. Nome e documento são obrigatórios fora do sandbox. properties: name: type: string maxLength: 100 description: >- Nome do titular da conta que vai pagar, como está no banco. Máximo de 100 caracteres. taxId: type: string description: >- CPF ou CNPJ do titular da conta que vai pagar, com ou sem pontuação. A autorização no banco é presa a este documento; um documento inválido é recusado com 400. email: type: string maxLength: 200 description: E-mail do assinante. Máximo de 200 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 os webhooks da assinatura (subscription.*) e de cada pagamento (payment.paid). Máximo de 500 caracteres. metadata: type: string maxLength: 2048 default: '{}' description: >- String JSON com dados livres, devolvida em todos os eventos da assinatura. Máximo de 2048 caracteres. frequency: type: string enum: - WEEKLY - MONTHLY - QUARTERLY - SEMIANNUALLY - ANNUALLY default: MONTHLY description: Periodicidade da renovação. dayGenerateCharge: type: integer minimum: 1 maximum: 28 description: >- Dia do mês do débito automático (1 a 28). Sem ele, o dia da compra. Não vale para a periodicidade semanal. example: productId: 65f0c2a1e4b0a1b2c3d4e5f6 customer: name: João Silva taxId: 529.982.247-25 email: joao@exemplo.com externalId: user_123 callbackUrl: https://minhaloja.com/webhooks/purincash metadata: '{"plano":"premium"}' frequency: MONTHLY dayGenerateCharge: 15 responses: '200': description: >- Assinatura criada. O primeiro pagamento e a autorização acontecem quando o cliente paga o QR. content: application/json: schema: type: object properties: paymentId: type: string description: >- Identificador do primeiro pagamento da assinatura (prefixo psa_sub_). As renovações têm o sufixo _c1, _c2… status: type: string description: Status do primeiro pagamento. Sempre "pending" na criação. type: type: string description: Tipo do pagamento. Sempre "subscription". subscriptionId: type: string description: >- Identificador da recorrência (29 caracteres, começa com R). É a chave estável entre todos os ciclos. authorizationStatus: type: string enum: - pending_authorization - active - rejected - expired - cancelled - ended - sandbox description: >- Estado da autorização no banco do cliente. Na criação é sempre pending_authorization (sandbox no ambiente de teste). amountCents: type: integer description: Valor de cada ciclo 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 - QUARTERLY - SEMIANNUALLY - ANNUALLY description: Periodicidade aplicada. environment: type: string enum: - live - sandbox description: Ambiente em que a assinatura foi criada. pix: type: object description: O QR composto do Pix Automático. properties: brCode: type: - string - 'null' description: >- Código PIX copia-e-cola (BR Code). Paga o primeiro ciclo e autoriza os próximos no mesmo ato. qrCodeImage: type: - string - 'null' description: Imagem do QR em data URI (PNG base64), ou null. paymentLinkUrl: type: - string - 'null' description: >- Sempre null no Pix Automático (mantido por compatibilidade). nextChargeDate: type: - string - 'null' format: date description: >- Data (YYYY-MM-DD) do primeiro débito automático, um período depois da compra. dayGenerateCharge: type: - integer - 'null' description: Dia do mês informado na criação, ou null. example: paymentId: psa_sub_a1b2c3d4... status: pending type: subscription subscriptionId: RN12345678202609200000000001 authorizationStatus: pending_authorization amountCents: 4990 currency: BRL productName: Premium Plan frequency: MONTHLY environment: live pix: brCode: 00020101021226760014br.gov.bcb.pix... qrCodeImage: data:image/png;base64,... paymentLinkUrl: null nextChargeDate: '2026-10-20' dayGenerateCharge: 15 '400': description: >- Parâmetro inválido ou ausente (ex. productId ausente ou com formato inválido, customer.name ausente, customer.taxId ausente ou com dígitos verificadores errados, callbackUrl inválida). Também retornado se subaccountId vier preenchido (null e vazio são ignorados), porque assinatura não credita ledger de subconta. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- customer.taxId (CPF or CNPJ of the payer) 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: O provedor de PIX recusou ou não respondeu ao criar a recorrência. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Pix Automático ainda não habilitado nesta loja. Fale com o suporte. 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_). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.