Subscriptions

Recurring billing on credit card, with renewal managed by the platform.

A subscription is the recurring billing arrangement on credit card. The integrator starts the subscription once, and the platform makes the charges of the following cycles on the card provided, without a new request. The integrator neither schedules charges nor stores card data.

​

Prerequisite

The amount and the billing interval of the subscription derive from a plan previously configured on the account. The plan is identified, in the request, by the productId and offerSlug fields. The interval may be weekly, monthly, bimonthly, quarterly, semiannual or annual.

​

Starting the subscription

Starting a subscription comprises two operations. The first converts the card data into a token, through POST /card-token, as described in Credit card. The second, POST /subscriptions, makes the first charge and creates the subscription.

curl -X POST https://api.fincle.com.br/subscriptions \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4e7a9c12-6b38-4f05-8d21-9a3c5e7f1b64" \
  -d '{
    "productId": "cmdg7h2k1000c1yjn4d8w6r3s",
    "offerSlug": "monthly-plan",
    "description": "License agreement no. 4587",
    "postbackUrl": "https://api.example.com/webhooks/fincle",
    "card": { "cardToken": "tok_9f2c1a7b4d6e" },
    "customer": {
      "name": "Helena Martins Andrade",
      "email": "[e-mail]",
      "documentType": "cpf",
      "document": "31845792041"
    }
  }'

The request contains neither an amount nor a number of installments: the amount is that of the plan, and recurring charges are always made as a single payment.

{
  "success": true,
  "message": "Assinatura criada com sucesso",
  "data": {
    "transaction": {
      "id": "cmddiqpxo09zf1yju2kqkhgga",
      "status": "paid",
      "card": { "token": "tok_9f2c1a7b4d6e", "brand": "visa", "last4": "1111" },
      "fees": 995
    },
    "subscription": {
      "id": "cmdh1m4q2000e1yjn7f2z9t5v",
      "status": "active",
      "nextChargeAt": "2026-12-12T14:08:06.000Z"
    }
  }
}

Field	Description
transaction	Transaction corresponding to the first charge, with the outcome of the authorization.
subscription.id	Subscription identifier.
subscription.status	Status of the subscription.
subscription.nextChargeAt	Time scheduled for the next charge.

​

First charge declined

The subscription is created only when the first charge is authorized. If it is declined, the response keeps status 200, contains the transaction in the refused status, with the reason in refuseReason, and does not contain the subscription block. It is for the integrator to obtain another card and submit a new request.

A 400 response indicates that the plan was not found or is not configured as recurring. The temporary block of the payer described in Credit card applies to this operation.

​

Statuses

Status	Description
active	Subscription in force, with charges up to date.
overdue	Subscription with an unauthorized renewal charge, within the retry period.
cancelled	Subscription cancelled, by act of the integrator, the payer or the platform.
completed	Subscription ended upon reaching the number of charges set in the plan.
failed	Subscription ended by failure.

​

Renewal

At each cycle, the platform makes the charge on the card linked to the subscription. Each renewal charge is a transaction of its own and generates the ordinary transaction notifications, including transaction_paid, described in Webhooks.

​

Renewal failure

A declined renewal charge moves the subscription to the overdue status, and the platform makes further charge attempts. Authorization of a further attempt restores the active status. Upon the fifth attempt without authorization, the subscription is cancelled by the platform.

​

Cancellation

The POST /subscriptions/{subscriptionId}/cancel operation cancels the subscription. From cancellation onwards, no further charge is made.

curl -X POST https://api.fincle.com.br/subscriptions/cmdh1m4q2000e1yjn7f2z9t5v/cancel \
  -H "Authorization: Bearer $FINCLE_TOKEN"

Cancellation does not return amounts already paid. The return of a specific charge depends on the refund of the corresponding transaction. The operation responds 400 when the subscription is already cancelled or completed.

​

Retrieval

The GET /subscriptions/{subscriptionId} operation returns the subscription, with its status, the date of the next charge, the plan contracted and the identification of the payer. The GET /subscriptions operation lists the subscriptions of the account, filtered by plan (productId, offerId), status (status), period and search text, and paginated by the page and limit parameters.

The listing also contains consolidated indicators in the stats block.

Field	Description
activeSubscriptions	Number of active subscriptions.
monthlyRecurringRevenueInCents	Monthly recurring revenue, in cents.
lifetimeValueInCents	Accumulated value, in cents.
churnRate	Cancellation rate.
totalSubscriptions	Total number of subscriptions.
cancelledSubscriptions	Total number of cancelled subscriptions.