Assinaturas

Assinaturas representam recorrências vinculadas a um cliente e a um produto. Use esse fluxo quando sua operação precisa cobrar o cliente de forma recorrente, com regras de produto, vencimento e pagamento associadas. Na Veepag, existem dois caminhos principais para criar assinaturas. A versão v1 cria a assinatura e já tenta o pagamento; a versão v2 cria a assinatura e a cobrança, mas deixa o pagamento para outro momento.

Criar assinatura v1

POST /v1/subscription cria a assinatura, gera a cobrança e tenta o pagamento imediato. Esse fluxo é útil quando você já tem os dados necessários para iniciar a recorrência e cobrar o cliente no mesmo momento. Campos obrigatórios confirmados:

Campo	Regra
`companyId`	String obrigatória.
`product.id`	ID do produto.
`paymentMethod`	Enum `CREDIT_CARD`, `DEBIT_CARD`, `BOLETO` ou `PIX`.
`paymentProfile`	Obrigatório para `CREDIT_CARD`: `holderName`, `cardNumber`, `cardExpiration`.
`client.name`	Obrigatório quando `client` é enviado.
`client.doc` ou `client.cpf`	CPF/CNPJ válido.

curl --request POST 'https://sandbox.api.veepag.com/v1/subscription' \
  --header 'apiKey: keyId.secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "companyId": "company_id",
    "product": { "id": "product_id" },
    "paymentMethod": "CREDIT_CARD",
    "installments": 1,
    "client": {
      "name": "Maria Silva",
      "doc": "12345678909",
      "email": "maria.silva@example.com"
    },
    "paymentProfile": {
      "holderName": "MARIA SILVA",
      "cardNumber": "4111111111111111",
      "cardExpiration": "10/2026",
      "cardCvv": "123"
    },
    "metadata": {
      "externalOrderId": "pedido_123"
    }
  }'

Use metadata para guardar identificadores da sua aplicação, como pedido, contrato ou plano interno. Isso facilita conciliação e suporte depois.

Resposta da criação v1

A resposta do v1 confirma a criação da assinatura e também mostra o resultado da tentativa de pagamento dentro de charge. Isso é importante: o endpoint pode retornar 201 porque a assinatura foi criada, mas o pagamento pode ter sido aprovado ou recusado. Para saber o resultado financeiro da tentativa, leia os campos de charge.

{
  "id": "subscription_id",
  "transactionId": ["transaction_id"],
  "status": "ACTIVE",
  "nextCharge": "2026-07-23T12:00:00.000Z",
  "paymentMethod": "CREDIT_CARD",
  "charge": {
    "statusCode": 200,
    "amount": {
      "value": 9900,
      "currency": "BRL"
    },
    "status": "PAID",
    "message": "Pagamento aprovado",
    "acquirer": {},
    "qrCode": null,
    "boleto": null
  }
}

Campo	Como interpretar
`id`	Identificador da assinatura criada.
`transactionId`	Lista de transações criadas durante a tentativa de pagamento.
`status`	Status atual da assinatura depois da tentativa de cobrança.
`nextCharge`	Próxima data de cobrança da assinatura, quando disponível.
`paymentMethod`	Meio de pagamento usado na tentativa.
`charge.statusCode`	Resultado da tentativa de pagamento: `200` para aprovado ou `402` para pagamento não aprovado.
`charge.status`	Status da cobrança após a tentativa.
`charge.message`	Mensagem retornada pelo fluxo de pagamento.
`charge.acquirer`	Dados retornados pela adquirente, quando disponíveis.
`charge.qrCode`	Dados de Pix, quando o meio de pagamento gerar QR Code.
`charge.boleto`	Dados de boleto, quando o meio de pagamento gerar boleto.

Para confirmar se o pagamento foi aprovado, use charge.statusCode, charge.status e charge.message. O HTTP 201 indica que a criação da assinatura foi processada; ele não significa, sozinho, que o pagamento foi aprovado.

Criar assinatura v2

POST /v2/subscription cria a assinatura e a cobrança, mas não tenta o pagamento imediato. Esse caminho é melhor quando o cliente já existe na Veepag e você quer controlar o momento do pagamento separadamente. Principais diferenças:

v1	v2
Cliente inline em `client`	Cliente existente em `clientId`
Produto em `product.id`	Produto em `productId`
Pagamento imediato	Cria subscription + charge sem pagamento
Não recebe `dueDate` no DTO público	`dueDate` obrigatório

Resposta da criação v2

Como o v2 não tenta pagamento imediato, a resposta não traz sucesso ou falha de transação. Ela retorna os objetos criados para você seguir o fluxo no seu próprio momento.

{
  "subscription": {
    "_id": "subscription_id",
    "status": "CREATED"
  },
  "charge": {
    "_id": "charge_id",
    "status": "ACTIVE"
  }
}

Use o v2 quando a sua integração já tem um clientId, quer definir uma data de vencimento em dueDate e prefere conduzir o pagamento depois.

Cancelar assinatura

PUT /v1/subscription/cancel cancela uma assinatura. Use esse endpoint quando o cliente encerrou a recorrência ou quando sua operação precisa interromper cobranças futuras.

{
  "companyId": "company_id",
  "subscriptionId": "subscription_id"
}

Resposta confirmada:

{
  "success": true,
  "message": "Assinatura cancelada com sucesso."
}

Criação em lote

POST /v1/subscription/list recebe companyId e list. O processamento é assíncrono por fila, com blocos de 3.000 itens e delay de 15 minutos entre blocos.

O schema dos itens de list não está tipado na codebase (z.any()). Antes de usar esse endpoint em produção, confirme o layout esperado com o time Veepag.

Para lotes grandes, recomendamos validar primeiro com uma amostra pequena no sandbox. Assim você confirma o formato dos dados e evita retrabalho em massa.

Comece aqui

Guias

API Reference

Criar assinatura v1

Resposta da criação v1

Criar assinatura v2

Resposta da criação v2

Cancelar assinatura

Criação em lote

​Criar assinatura v1

​Resposta da criação v1

​Criar assinatura v2

​Resposta da criação v2

​Cancelar assinatura

​Criação em lote

Criar assinatura v1

Resposta da criação v1

Criar assinatura v2

Resposta da criação v2

Cancelar assinatura

Criação em lote