---
title: "Criar assinatura"
method: POST
path: "/subscriptions"
---

# Criar assinatura

`POST /subscriptions`

## Headers

- `Authorization` string, required
- `x-idempotency-key` string

## Request body

- object
  - `reference_id` string — Identificador da assinatura na sua aplicação (MAX 65 caracteres). ⚠️**Obrigatório**⚠️
  - `plan` object — Objeto contendo informações do plano que será usado na assinatura. ⚠️**Obrigatório**⚠️
    - `id` string — Identificador de um plano existente e ativo no qual a assinatura será associada. Formato `PLAN_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`.
  - `customer` object — Se você está criando a assinatura para um assinante já cadastrado, você precisa fornecer apenas o respectivo `id` do assinante, desconsiderando os demais parâmetros. <br/> Se você deseja cadastrar um novo assinante com a criação da assinatura, forneça todos os parâmetros marcados como ⚠️**Obrigatório**⚠️. Para esse cenário, você não deve informar o parâmetro `id`.
    - `id` string — Código de identificação do assinante. ⚠️ **Importante: caso esteja utilizando um assinante já existente, basta passar esse id e os outros dados de customer não são necessários.**⚠️ Formato `CUST_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`.
    - `reference_id` string — Identificador único atribuído para o assinante. Utilizado internamente pelo vendedor em seu sistema (Max 65 caracteres).
    - `name` string — Nome completo do assinante (Max 150 caracteres). ⚠️**Obrigatório caso o `id` não seja fornecido.**⚠️
    - `email` string — E-mail válido do assinante (Max 60 caracteres). ⚠️**Obrigatório caso o `id` não seja fornecido.**⚠️
    - `tax_id` string — Número do documento do assinante, CPF com 11 dígitos e CNPJ com 14 dígitos numéricos. ⚠️**Forneça apenas números. Obrigatório caso o `id` não seja fornecido.**⚠️
    - `phones` object[] — Objeto contendo o(s) telefone(s) do assinante. ⚠️**Deve conter no mínimo um telefone. Obrigatório caso o `id` não seja fornecido.**⚠️
      - `country` string — Código de area do país. ⚠️ **Obrigatório, somente código do Brasil(55) aceito no momento. **⚠️<br><small>Exemplo: 55 (Brasil)</small>
      - `area` string — Código do estado (DDD) do telefone (Max 3 caracteres). ⚠️ **Obrigatório**⚠️
      - `number` string — Telefone do assinante (Max 9 caracteres). ⚠️ **Obrigatório**⚠️
    - `birth_date` string, date — Data de nascimento do assinante.
    - `address` object — Objeto de detalhes do endereço do assinante.
      - `street` string — Logradouro do endereço (Max 150 caracteres). Não são aceitos caracteres especiais. ⚠️ **Obrigatório** ⚠️
      - `number` string — Número do endereço (Max 8 caracteres). ⚠️ **Obrigatório** ⚠️
      - `complement` string — Complemento do endereço (Max 40 caracteres), ⚠️ **Não aceita espaços entre palavras.**⚠️
      - `locality` string — Bairro do assinante (Max 60 caracteres).⚠️ **Obrigatório** ⚠️
      - `city` string — Cidade do assinante (Max 60 caracteres). ⚠️ **Obrigatório** ⚠️
      - `region_code` string — Estado (sigla) do assinante (Max 2 caracteres). ⚠️ **Obrigatório** ⚠️ <br><small>Exemplo: MG </small>.
      - `postal_code` string — CEP do endereço (8 caracteres). ⚠️ **Apenas dígitos numéricos. Obrigatório.** ⚠️
      - `country` 'BRA' — País em formato ISO-alpha3. ⚠️**No momento, apenas o valor BRA é aceito.** ⚠️ <br><small>Exemplo BRA.</small>
    - `billing_info` object[] — Array com os objetos contendo os dados de pagamento do assinante.
      - `type` '' | 'CREDIT_CARD' — Deve ser informado o CREDIT_CARD. ⚠️**Obrigatório**⚠️
      - `card` object — Objeto com os dados do cartão. ⚠️**Obrigatório**⚠️
        - `encrypted` string — Dados do cartão criptografados. Para aprender como criptografar o cartão, acesse a página de [Criptografia](https://developer.pagbank.com.br/docs/criptografia-e-chave-publica). ⚠️**Obrigatório quando o integrador NÃO possuir certificação PCI. Caso este parâmetro seja preenchido, nenhum outro parâmetro deverá ser enviado.**⚠️
        - `number` string — Número do cartão do assinante (Min 14; Max 19 caracteres).
        - `security_code` integer — Código de segurança do cartão (CVV) (Min 3; Max 4 digitos). ⚠️**Obrigatório para realizar a validação do cartão antes de criar o assinante.**⚠️
        - `exp_year` string — Ano de expiração do cartão (2 ou 4 digitos). <br><small>Exemplo: 23 ou 2023.</small>
        - `exp_month` string — Mês de expiração do cartão (2 digitos). <br><small>Valores aceitos entre 01 e 12.</small>
        - `holder` object — Objeto com detalhes do dono do cartão.
          - `name` string — Nome do dono do cartão (Min 2; Max 30 caracteres). ⚠️Obrigatório⚠️
          - `birth_date` string — Data de nascimento do dono do cartão.
          - `tax_id` string — Esse campo aceita somente um CPF ou CNPJ válido. Entre 11 e 14 caracteres e apenas números.
          - `phone` object — Telefone do dono do cartao.
            - `country` string — Código de area do país. ⚠️ **Obrigatório, somente código do Brasil(55) aceito no momento. **⚠️<br><small>Exemplo: 55 (Brasil)</small>
            - `area` string — Código do estado (DDD) do telefone (Max 3 caracteres). ⚠️ **Obrigatório**⚠️
            - `number` string — Telefone do assinante (Max 9 caracteres). ⚠️ **Obrigatório**⚠️
  - `coupon` object — Objeto contendo informações do cupom de desconto, quando aplicável.
    - `id` string — Código de identificação do cupom a ser aplicado a essa assinatura. Formato `COUP_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`.
  - `payment_method` object[] — Objeto contendo as informações de pagamento que o assinante optou para aderir a essa assinatura. ⚠️**Obrigatório**⚠️
    - `type` 'CREDIT_CARD' | 'BOLETO', required — Tipo de meio de pagamento.
    - `card` object — Dados do cartão de credito. ⚠️ **Este campo é obrigatório se o type informado for `CREDIT_CARD`. ** ⚠️
      - `security_code` integer — Código de segurança do cartão (CVV) (Min 3; Max 4 caracteres). ⚠️**Obrigatório**⚠️
  - `amount` object — Objeto contendo as informações do valor a ser cobrado. Se não informado, será utilizado o valor definido no momento da criação do plano vinculado à assinatura para criar a cobrança.
    - `value` integer — Valor a ser estornado em centavos (MAX 9 caracteres). <br><small>Exemplo: R$ 1.500,99 = 150099</small> ⚠️**Obrigatório**⚠️
    - `currency` string — Código de moeda ISO de três letras, em maiúsculas. No momento, apenas o Real brasileiro (BRL) é suportado. ⚠️ **Obrigatório** ⚠️
  - `pro_rata` boolean — Campo para especificar se assinatura deve ser criada com pró-rata ou não. <br><small>Valores: `True` ou `False`</small>
  - `best_invoice_date` object — Objeto com melhor data para próxima cobrança
    - `day` string — Melhor dia para pagar (Max 2 caracteres).
    - `month` string — Melhor mês para pagar (Max 2 caracteres).
  - `split_enabled` boolean — Define se o recurso de divisão de pagamento (split) será ativado para assinaturas. Quando definido como `true`, o split será aplicado conforme a configuração do objeto `split`. <br/> ⚠️ **Caso não deseje utilizar o recurso não é envie esse parâmetro `false`.**
  - `splits` object — Objeto que define as regras de divisão (percentual ou valor fixo) de uma transação recorrente (assinatura) entre até 15 recebedores. <br/> ⚠️ **Obrigatório quando `split_enabled` for `true`.** <br/>🚫 **Não deve ser enviado quando `split_enabled` for `false` ou não estiver presente.**
    - `method` 'PERCENTAGE' | 'FIXED' — Define o método de divisão do pagamento a ser utilizado ⚠️**Obrigatório**⚠️. <br/> - `PERCENTAGE`: Divisão proporcional ao valor percentual informado. <br/> - `FIXED`: Divisão por valores fixos.
    - `receivers` object[] — Listas dos recebedores. Para cada recebedor, você deve informar a conta e o valor a ser recebido ⚠️**Obrigatório**⚠️. <br/> Caso `method = PERCENTAGE`, a soma dos valores deve ser igual a 100. <br/> Caso `method = FIXED`, a soma dos valores atribuídos a cada recebedor não pode ultrapassar o valor da mensalidade.
      - `account` object — Objeto com as informações da conta do recebedor. ⚠️**Obrigatório**⚠️
        - `id` string — Identificador único da conta PagBank do recebedor.
      - `amount` object — Objeto com as informações da quantia, percentual ou fixa, a ser transferida para o recebedor. ⚠️**Obrigatório**⚠️
        - `value` integer — Valor, percentual ou fixo, a ser transferido para a conta PagBank do recebedor.

## Response `200`

200

- object
  - `id` string
  - `reference_id` string
  - `amount` object
    - `value` integer
    - `currency` string
  - `status` string
  - `plan` object
    - `id` string
    - `name` string
  - `payment_method` object[]
    - `type` string
    - `card` object
      - `token` string
      - `brand` string
      - `first_digits` string
      - `last_digits` string
      - `exp_month` string
      - `exp_year` string
      - `holder` object
        - `name` string
  - `next_invoice_at` string
  - `pro_rata` boolean
  - `customer` object
    - `id` string
    - `name` string
    - `email` string
  - `created_at` string
  - `updated_at` string
  - `exp_at` string
  - `links` object[]
    - `rel` string
    - `href` string
    - `media` string
    - `type` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/pagbank/apis/nova-plataforma-sandbox.md) · [All operations](https://skmtc.net/pagbank/apis/nova-plataforma-sandbox/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pagbank/nova-plataforma-sandbox/versions/05e64f3006ab/schema)