Criar nova assinatura

POSThttps://api.sandbox.cefispay.com.br/api/v1/subscriptions

RECIPES

Criar plano e assinatura recorrenteAbrir recipe

Cria uma nova assinatura, que representa uma cobrança recorrente, vinculando um cliente a um plano específico. Cartão de crédito: se a assinatura for cobrada no cartão, o cadastro do cliente precisa ter CPF ou CNPJ, telefone, CEP e número do endereço. Esses dados são enviados à adquirente como dados do titular, e a cobrança é recusada se algum deles estiver faltando. Recomendamos cadastrar o cliente com o máximo de informações possível, mesmo que hoje você só cobre por boleto ou Pix.

Parâmetros do body

obrigatórioapplication/json

Descreve os dados a serem incluídos no corpo da requisição.

customerobjectobrigatório
customer object
- idnumberobrigatório
  O ID do cliente na NinePay. Se você ainda não tem o ID do cliente, utilize o endpoint de criação de Cliente para fazer o cadastro e receber o ID.
planobjectobrigatório
plan object
- idnumberobrigatório
  O ID do plano a que a nova assinatura será vinculada.
coupon_codesarray de strings
productsarray de objects
Opcional. Os produtos da assinatura, cobrados junto do plano. Enviados aqui, eles entram já na primeira cobrança, e não apenas nas seguintes. Quando o plano tem trial, a primeira cobrança continua sendo R$ 0,00 e os produtos entram na cobrança seguinte ao trial. Os produtos também podem ser anexados depois da criação, pelo endpoint de produtos da assinatura.

Respostas

200Assinatura criada com sucesso

Corpo da resposta

application/json

subscriptionobjectSubscription
subscription object
Ver schema Subscription
customerobjectCustomer
customer object
Ver schema Customer

Exemplo

{
  "subscription": {
    "id": 42,
    "uuid": "8b2cad02-06f0-42be-84ac-101b23a1bb0d",
    "amount": 2500,
    "plan_id": 2500,
    "status": "credit",
    "created_at": "2017-07-21 05:20:00"
  },
  "customer": {
    "id": 42,
    "name": "Jhon Doe",
    "email": "jhon@doe.com",
    "cpf": "833.828.600-15",
    "cnpj": "95.135.209/0001-79",
    "phone": "(11) 11111-1111",
    "cep": "01423-910",
    "address": "Rua José Maria Lisboa",
    "number": 42,
    "district": "Jardim Paulista",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }
}

401Não autenticado

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "AUTHENTICATION_ERROR",
  "message": "Não autenticado.",
  "timestamp": "2026-10-22T12:03:44+00:00",
  "request_id": "f2a7e962-6083-4525-816e-f14d4a602e0a",
  "documentation_url": "https://docs.ninepay.com.br"
}

422Erro na validação dos dados

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "VALIDATION_ERROR",
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O campo email é obrigatório."
    ]
  },
  "timestamp": "2026-10-22T12:03:54+00:00",
  "request_id": "64d62d36-e797-45ed-a9d5-c203bde81032",
  "documentation_url": "https://docs.ninepay.com.br",
  "suggestion": "Corrija os campos e tente novamente."
}

500Erro inesperado

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "UNEXPECTED_ERROR",
  "message": "Houve um erro inesperado.",
  "timestamp": "2026-10-22T12:04:46+00:00",
  "request_id": "868443d3-38fd-4c92-8ea8-7cccbbce4308",
  "documentation_url": "https://docs.ninepay.com.br",
  "suggestion": "Verifique todos os parâmetros da requisição. Se o erro persistir, entre em contato com nossa equipe em ti@ninepay.com.br."
}

RECIPES

Parâmetros do body

Respostas

Credenciais

Resposta