Criar assinatura com cartão

POST/api/v1/subscriptions/

{
  "value": 2990,
  "cycle": "MONTHLY",
  "nextDueDate": "2026-10-15",
  "endDate": "2027-10-01",
  "description": "Plano Premium",
  "externalReference": "cliente_123",
  "payerName": "Joao da Silva",
  "payerDocument": "52998224725",
  "payerEmail": "[email protected]",
  "payerPhone": "11999999999",
  "cardNumber": "4111111111111111",
  "cvv": "123",
  "expirationDate": "12/2028",
  "cardHolder": "JOAO DA SILVA",
  "callbackUrl": "https://meu-sistema.com/webhook/subscription"
}

Campo	Tipo	Obrigatório	Descrição
`value`	integer	Sim	Valor em centavos, inteiro de `1` a `2147483647`. R$ 29,90 = `2990`
`cycle`	string	Sim	Ciclo de cobrança, em maiúsculas — ver Referência de status
`nextDueDate`	string	Sim	Primeiro vencimento, `YYYY-MM-DD`. Hoje ou depois, no horário de Brasília
`endDate`	string	Não	Data final, `YYYY-MM-DD`, igual ou posterior a `nextDueDate`. Omitido → roda indefinidamente
`description`	string	Não	Descrição da assinatura. Máx. 255 caracteres
`externalReference`	string	Não	Referência no seu sistema. Máx. 100 caracteres. Recomendado: o ID do cliente no seu cadastro (ver Escopo da plataforma)
`payerName`	string	Sim	Nome completo do pagador. Máx. 100 caracteres
`payerDocument`	string	Sim	CPF ou CNPJ com dígito verificador válido, com ou sem pontuação. Máx. 20 caracteres
`payerEmail`	string	Não	E-mail do pagador. Máx. 100 caracteres
`payerPhone`	string	Não	Telefone do pagador. Máx. 20 caracteres
`callbackUrl`	string	Não	URL dos webhooks da seção Webhooks de cobrança. HTTPS público (veja as regras do endpoint), ou vazio para desligar. Máx. 500 caracteres
Cartão		Condicional	Uma das três formas abaixo, ou nenhuma (Caminho B)

aviso

Campos que esta rota não conhece são ignorados. Isso é diferente da edição (Atualizar assinatura), que recusa campos não editáveis. Não envie campos fora desta tabela: eles não têm efeito e podem passar a ser recusados no futuro, com aviso.

Validações antes de qualquer cobrança

Estas regras são conferidas antes de chamar o adquirente. Nenhuma delas cria a assinatura.

Situação	Resposta `400`
`value` com fração, zero, negativo ou acima de `2147483647`	`Invalid value (expected positive integer cents, max 2147483647)`
`nextDueDate` anterior a hoje	`nextDueDate não pode ser anterior a hoje`
`endDate` anterior a `nextDueDate`	`endDate precedes nextDueDate`
`cycle` fora da lista da seção Referência de status	`cycle inválido (use WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY ou YEARLY)`
`payerDocument` que não é CPF nem CNPJ válido	`payerDocument inválido (informe um CPF ou CNPJ válido)`
`callbackUrl` que não é HTTPS público	`callbackUrl must be a safe public HTTPS URL`
Texto maior que o limite da tabela	`<campo> excede <n> caracteres`
Bandeira não reconhecida pelo número	`Bandeira do cartão não reconhecida`
Número do cartão com dígito verificador inválido	`Número do cartão inválido`
`expirationDate` fora de `MM/AAAA` (ou `MM/AA`) ou com mês fora de 01–12	`Data de validade inválida (use MM/AAAA)`
Cartão vencido	`Cartão vencido`

Por que a data passada é recusada

Sem essa regra, uma assinatura com vencimento três meses atrás nascia ACTIVE e o processamento cobrava todos os ciclos atrasados. Mesmo que uma assinatura fique atrasada por outro motivo, a YumePay não cobra ciclos em lote (Processamento das cobranças).

As três formas de informar o cartão

Forma	Campos	Quando usar
Em claro	`cardNumber`, `cvv`, `expirationDate` (`MM/YYYY`), `cardHolder`	Seu servidor recebe o cartão. Os quatro campos andam juntos
Criptografado	`encryptedCardData` (ou `encrypted_card_data`)	O cartão é cifrado no navegador e seu servidor nunca vê o número. Mesma chave, padding e JSON da seção Montar o seu próprio checkout, passo 1. Nenhum campo em claro é necessário
Reaproveitado	`sourceSubscriptionId`	O mesmo pagador já tem outra assinatura com cartão. O cartão dela é copiado, sem pedir os dados de novo

Exemplo com cartão criptografado

{
  "value": 2990,
  "cycle": "MONTHLY",
  "nextDueDate": "2026-10-15",
  "payerName": "Joao da Silva",
  "payerDocument": "52998224725",
  "encryptedCardData": "base64_da_criptografia_RSA..."
}

Exemplo reaproveitando o cartão de outra assinatura do mesmo pagador

{
  "value": 4990,
  "cycle": "MONTHLY",
  "nextDueDate": "2026-10-15",
  "payerName": "Joao da Silva",
  "payerDocument": "52998224725",
  "sourceSubscriptionId": 12
}

Envie só uma forma. Combinar duas devolve 400 Envie apenas uma forma de cartão.

Regras do reaproveitamento (`sourceSubscriptionId`)

Situação	Resposta
Origem do mesmo lojista, com cartão, mesmo `payerDocument` válido	Cartão copiado. Sem nova tokenização
Origem com outro `payerDocument`, sem documento ou com documento inválido	`409 Source subscription belongs to a different payer`
Origem sem cartão tokenizado (ex.: ainda `PENDING_PAYMENT`)	`409 Source subscription has no reusable card`
Origem de outro lojista	`403`
Origem inexistente	`404`

A titularidade é validada pela YumePay: um cartão nunca é vinculado a outro pagador. A comparação usa só os dígitos — 529.982.247-25 e 52998224725 são o mesmo documento — e exige um CPF ou CNPJ válido.
A origem pode estar em qualquer status, inclusive cancelada — útil para recontratar um cliente sem pedir o cartão de novo.
As duas assinaturas passam a usar o mesmo cartão. Trocar o cartão de uma (Trocar o cartão) não altera a outra.

Cartão recusado na criação

Há dois momentos em que a recusa pode acontecer, com respostas diferentes:

Momento	Resposta	A assinatura
Na tokenização — o adquirente rejeita o cartão em si	`422 CARD_REJECTED` com o motivo em `denial` (Respostas de erro)	Não é criada
Na primeira cobrança — o cartão tokeniza, mas a cobrança do dia é negada (só quando `nextDueDate` é hoje)	`201` com `status: 0`, `lastChargeStatus: "DENIED"` e `consecutiveDeniedCharges: 1`	É criada `ACTIVE`, sem valor capturado

aviso

Na criação com vencimento hoje, confira lastChargeStatus na resposta 201. "CONFIRMED" = primeira cobrança aprovada; "DENIED" = assinatura criada, mas nada capturado. Nesse caso, a decisão é sua: pedir outro cartão (Trocar o cartão), aguardar a retentativa (Retentativa de cobrança negada) ou cancelar (Cancelar assinatura). O motivo da recusa está na cobrança (Listar cobranças de uma assinatura) e chega no webhook charge.denied.

Os casos que o adquirente recusaria na tokenização sem motivo útil (número inválido, validade inválida, cartão vencido) já são barrados antes, com 400 e mensagem própria. O 422 fica para recusas que só o adquirente pode decidir. 502 indica falha de comunicação com o adquirente, não recusa — pode repetir.

Resposta 201

{
  "status": "success",
  "data": {
    "id": 12,
    "merchantId": 2,
    "status": 0,
    "value": 2990,
    "amount": 29.9,
    "cycle": "MONTHLY",
    "nextDueDate": "2026-10-15",
    "endDate": "2027-10-01",
    "description": "Plano Premium",
    "externalReference": "cliente_123",
    "payerName": "Joao da Silva",
    "payerDocument": "52998224725",
    "payerEmail": "[email protected]",
    "payerPhone": "11999999999",
    "cardLastFour": "1111",
    "cardBrand": "Visa",
    "cardExp": "12/2028",
    "callbackUrl": "https://meu-sistema.com/webhook/subscription",
    "paymentGuid": "",
    "paymentUrl": "",
    "lastChargeStatus": null,
    "lastChargeAt": null,
    "consecutiveDeniedCharges": 0,
    "createdAt": "2026-10-09T12:48:57.28966Z",
    "updatedAt": "2026-10-09T12:48:57.28966Z"
  }
}

Se o vencimento for hoje, a cobrança já foi feita quando você recebe esta resposta: com aprovação, nextDueDate já aponta para o próximo ciclo e lastChargeStatus vem "CONFIRMED".

Validações antes de qualquer cobrança​

As três formas de informar o cartão​

Exemplo com cartão criptografado​

Exemplo reaproveitando o cartão de outra assinatura do mesmo pagador​

Regras do reaproveitamento (sourceSubscriptionId)​

Cartão recusado na criação​