Create a subscription with credit card

Create a subscription so that Asaas generates recurring payments and charges the card on the due dates.

At creation, the card is validated. The first charge occurs on nextDueDate, unless that date is the current day.

When to use

Use this flow when your integration needs to:

• make recurring credit card charges;
• reuse the same card in subsequent cycles;
• validate the card at sign-up;
• automate charging without requesting the card details at each due date.

Before you start

Before creating the subscription:

• register the customer and store their ID;
• define the amount, frequency, and first due date;
• configure the subscription and payment Webhooks;
• use HTTPS if your application captures card details.

If you already have a valid creditCardToken for the customer, prefer to use it instead of the full card details.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Register or look up the customer"] --> B["Provide the card"]
    B --> C["Create the subscription"]
    C --> D["Validate the card"]
    D --> E["Generate the payments"]
    E --> F["Process each due date"]
    F --> G["Receive the Webhooks"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

The validation performed at creation does not guarantee approval of future charges. The card may expire, be blocked, canceled, or run out of limit before a subsequent due date.

1. Create the subscription

Use:

POST /v3/subscriptions

Example with card details:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2027-01-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "description": "Pro Plan",
  "creditCard": {
    "holderName": "Marcelo Henrique Almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2030",
    "ccv": "318"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  },
  "remoteIp": "203.0.113.10"
}

In remoteIp, provide the IP of the device used by the payer. Do not send your server's IP.

See the endpoint Create subscription with credit card.

Using a tokenized card

If you already have a valid token for the customer, use creditCardToken instead of creditCard and creditCardHolderInfo:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2027-01-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99",
  "remoteIp": "203.0.113.10"
}

The token belongs to the customer who originated it and cannot be reused for another customer.

See Credit card tokenization.

Expected result

The API returns the created subscription and its id.

Store this identifier to track, update, or delete the subscription.

If nextDueDate is the current date, the first charge may be processed immediately.

2. Track the subscription and payments

Prefer Webhooks to keep your application in sync with Asaas.

Use the Events for subscriptions to track changes in the subscription lifecycle.

Use the Events for payments to track each generated payment and its card processing.

3. Update the subscription details

To change information such as amount, due date, or frequency, use:

PUT /v3/subscriptions/{id}

By default, changes affect the payments that are yet to be generated.

When you need to also apply the supported changes to existing pending payments, provide:

{
  "updatePendingPayments": true
}

For amount or due date changes in credit card subscriptions, the tokenization feature must be enabled.

Tokenization is available for testing in Sandbox. In production, the feature must be enabled for your account. To request it, contact Asaas support. Enabling it is subject to a review of your account information and operation.

See the endpoint Update existing subscription.

4. Update the subscription's card

To replace only the card used in the recurrence, without making an immediate charge, use:

PUT /v3/subscriptions/{id}/creditCard

If you have a token for the new card:

{
  "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99",
  "remoteIp": "203.0.113.10"
}

You can also send creditCard and creditCardHolderInfo instead of the token.

The update:

• does not make an immediate charge;
• changes the subscription's card;
• also updates the pending payments linked to the subscription to use the new card.

See the endpoint Update subscription credit card.

Common errors

If the subscription is not created, check:

• whether the card was declined;
• whether the card and cardholder details are valid;
• whether the customer belongs to the account;
• whether the required fields were sent;
• whether remoteIp corresponds to the payer's device.

Creation may return HTTP 400 when the data sent or the card processing prevents the operation.

Do not automatically repeat a request without evaluating the previous response, especially in timeout scenarios.

Test in Sandbox

Use the dedicated test cards to validate approvals, declines, tokenization, and Webhooks before using the flow in Production.

See Testing credit card payments.

Next steps

• Tokenize cards for reuse
• Update the subscription's credit card
• Track subscription events
• Track payment events
• Test credit card payments
• See the Subscriptions FAQ