Criando assinatura com cartão de crédito

Assim como na cobrança, os dados do cartão e do portador podem ser enviados na requisição de criação da assinatura para que o pagamento já seja processado. A diferença é que no caso da cobrança o cartão do cliente é cobrado no momento da criação da mesma, já no caso da assinatura, o cartão será validado no momento da criação, porém a cobrança será feita somente no vencimento da primeira mensalidade. É importante ressaltar que a validação feita no momento a criação não garante que cobrança ocorrerá com sucesso no vencimento, pois neste meio-tempo o cartão pode ter sido cancelado, expirado, não ter limite, entre outros.

Para tal, ao executar a requisição de criação da assinatura, basta enviar os dados do cartão de crédito juntamente com os dados do titular através dos objetos creditCard e creditCardHolderInfo. Se a transação for autorizada a assinatura será criada e a API retornará HTTP 200. Caso contrário a assinatura não será persistida e será retornado HTTP 400.

📘

Dica!

Caso você queira criar uma assinatura que a primeira cobrança será cobrada no ato da criação, informe o nextDueDate como a data atual.

Uma vez criada a assinatura com cartão de crédito, a cobrança será feita mensalmente (ou outra periodicidade definida) no cartão do cliente até que ele se torne inválido ou você remova a assinatura.

🚧

Atenção

• Caso você opte por capturar na interface do seu sistema os dados do cartão do cliente, é obrigatório o uso de SSL (HTTPS), caso contrário sua conta pode ser bloqueada para transações via cartão de crédito.
• Para se evitar timeouts e decorrentemente duplicidades na captura, recomendamos a configuração de um timeout mínimo de 60 segundos para este request.

POST /v3/subscriptions
Confira a referência completa deste endpoint

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2023-10-15",
  "value": 19.9,
  "cycle": "MONTHLY",
  "description": "Assinatura Plano Pró",
  "creditCard": {
    "holderName": "marcelo h almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2021",
    "ccv": "318"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223-005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  },
}

Como alterar a data de vencimento ou o valor?

Para conseguir alterar o valor ou vencimento de uma assinatura, você precisa obrigatoriamente ter a tokenização ativa em sua conta.

Essa funcionalidade permite você cobrar de seus clientes recorrentemente sem a necessidade deles informarem todos os dados de cartão de crédito novamente. Tudo isso de forma segura por meio de um token.

🚧

Atenção

• A funcionalidade de tokenização está previamente habilitada em Sandbox e você já pode testá-la. Para uso em produção, é necessário solicitar a habilitação da funcionalidade ao seu gerente de contas. A habilitação da funcionalidade está sujeita a análise prévia, podendo ser aprovada ou negada de acordo com os riscos da operação.
• O token é armazenado por cliente, não podendo ser utilizado em transações de outros clientes.

Para editar a assinatura você não precisa informar o token, mas precisa que ele esteja ativado em sua conta.

POST /v3/subscriptions/{id}
Veja a referência completa deste endpoint.

Além disso, ao atualizar o valor da assinatura ou forma de pagamento somente serão afetadas mensalidade futuras. Para atualizar as mensalidades já criadas mas não pagas com a nova forma de pagamento e/ou novo valor, é necessário passar o parâmetro updatePendingPayments: true.

Como alterar o cartão de crédito de uma assinatura?

Para alterar o cartão de crédito de uma cobrança, você precisa pegar a primeira cobrança pendente de uma assinatura e realizar o pagamento da mesma com o novo cartão.

🚧

A cobrança será paga na hora que você fizer a chamada ao endpoint. Todas as demais cobranças dessa mesma assinatura terão seus dados atualizados para o novo cartão.

Para pegar as cobranças em aberto de uma assinatura, faça uma chamada ao endpoint Listar cobranças de uma assinatura.

POST /v3/subscriptions/{id}/payments
Veja a referência completa deste endpoint.

Será retornado uma array com todos os pagamentos pendentes. Tendo o ID deles, basta fazer uma chamada ao endpoint de pagar uma cobrança com cartão de crédito.

POST /v3/payments/{id}/payWithCreditCard
Veja a referência completa deste endpoint.

{
  "creditCard": {
    "holderName": "marcelo h almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2021",
    "ccv": "318"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223-005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  }
}

Como poderia fazer upgrade de um plano de assinatura?

Pode acontecer de você ter um cliente que fez uma assinatura mensal, mas no meio do período quer mudar o plano para um superior, mais caro, por exemplo ou migrar para o plano anual. Se você tiver a tokenização ativa na sua conta, poderá alterar o valor da assinatura e/ou data, caso contrário, o recomendado é remover a assinatura atual e criar uma nova em seguida.

Caso o seu cliente tenha valores proporcionais para acertar, recomendamos verificar as cobranças em aberto, calcular qual seria o valor extra, gerar uma nova cobrança do valor poporcional e depois editar sua assinatura para os novos valores e/ou data.