Payments via credit card

Create card payments through the Asaas Invoice or send the payment details directly through the API.

When to use

Use card payments to:

• direct the customer to the Asaas Invoice;
• process the card in your application's checkout;
• reuse a tokenized card;
• create installment payments.

For recurring payments, see Subscriptions.

Before you start

You need to:

1. register or look up the customer;
2. store the ID returned by the API;
3. choose between the Asaas Invoice and your own checkout;
4. configure the payment Webhooks.

If your application captures card details, it must use HTTPS.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Register or look up the customer"] --> B{"Where will the payer enter the card?"}

    B --> BFatura(("Invoice"))
    B --> BAPI(("API"))

    BFatura --> C["Create the payment without card details"]
    C --> D["Redirect to invoiceUrl"]

    BAPI --> E["Send the card and cardholder details"]
    E --> F["Process the payment immediately"]

    D --> G["Track the status via Webhooks"]
    F --> G
    G --> H["Reconcile the payment"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    classDef respostaFatura fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px
    classDef respostaAPI fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px

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

    class BFatura respostaFatura
    class BAPI respostaAPI

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#8B5CF6,stroke-width:4px
    linkStyle 2 stroke:#22C55E,stroke-width:4px

1. Choose how the card will be entered

Use the Asaas Invoice

Create the payment without sending the card details:

POST /v3/payments

{
  "customer": "cus_000005219613",
  "billingType": "CREDIT_CARD",
  "value": 109.90,
  "dueDate": "2027-01-15",
  "externalReference": "ORDER-123"
}

The API will return the invoiceUrl field. Direct the customer to this URL so they can enter the card details in the Asaas interface.

See the endpoint: Create new payment with credit card.

Debit card

Debit card details cannot be sent directly through the API.

To offer this option, direct the customer to the invoiceUrl using billingType as CREDIT_CARD or UNDEFINED.

2. Process the card through the API

To process the payment in your application's checkout, send the creditCard and creditCardHolderInfo objects when creating the payment.

POST /v3/payments

{
  "customer": "cus_000005219613",
  "billingType": "CREDIT_CARD",
  "value": 100.00,
  "dueDate": "2027-01-15",
  "externalReference": "ORDER-123",
  "creditCard": {
    "holderName": "Marcelo Almeida",
    "number": "4444444444444444",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "ccv": "123"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223005",
    "addressNumber": "277",
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  },
  "remoteIp": "203.0.113.10"
}

In remoteIp, provide the IP of the payer's device, not the IP of your application's server.

Expected result

When the transaction is authorized:

• the payment will be created;
• the API will return HTTP 200;
• the payment will be processed at the time of the request.

When the transaction is declined:

• the payment will not be persisted;
• the API will return HTTP 400.

To test in Sandbox, see Test credit card payments.

3. Reuse the card with tokenization

After an approved transaction, the response may return the creditCardToken field.

In subsequent payments for the same customer, send the token instead of the creditCard and creditCardHolderInfo objects:

{
  "customer": "cus_000005219613",
  "billingType": "CREDIT_CARD",
  "value": 100.00,
  "dueDate": "2027-01-15",
  "creditCardToken": "76496073-536f-4835-80db-c45d00f33695",
  "remoteIp": "203.0.113.10"
}

You can also generate a token directly through the endpoint:

POST /v3/creditCard/tokenizeCreditCard

See the endpoint: Credit card tokenization.

4. Create an installment plan

For installment payments, provide installmentCount with installmentValue or totalValue.

Example:

{
  "customer": "cus_000005219613",
  "billingType": "CREDIT_CARD",
  "dueDate": "2027-01-15",
  "installmentCount": 10,
  "installmentValue": 200.00,
  "creditCardToken": "76496073-536f-4835-80db-c45d00f33695",
  "remoteIp": "203.0.113.10"
}

The limits are:

• up to 21 installments for Visa and Mastercard;
• up to 12 installments for other card brands.

For one-off payments, do not send installmentCount, installmentValue, or totalValue. Use only value.

See: Create an installment payment.

5. Track the payment

Configure Webhooks to track processing.

The main events are:

• PAYMENT_CONFIRMED: payment confirmed;
• PAYMENT_RECEIVED: amount available in the account;
• PAYMENT_CREDIT_CARD_CAPTURE_REFUSED: capture refused;
• PAYMENT_AWAITING_RISK_ANALYSIS: awaiting risk analysis;
• PAYMENT_REPROVED_BY_RISK_ANALYSIS: rejected in risk analysis.

See:

• Configure Webhooks
• Events for payments

Do not release the product or service based only on the payment's creation. Use the status and events applicable to your flow.

Common errors

For security reasons, a declined transaction may return a generic message:

{
  "errors": [
    {
      "code": "invalid_creditCard",
      "description": "Transaction not authorized. Check the credit card details and try again."
    }
  ]
}

If a decline occurs:

• do not expose internal details to the payer;
• advise them to review the details or use another card;
• log the returned code for analysis;
• check that the cardholder details match the issuer's records.

In case of a timeout or inconclusive response, query the payment before repeating the request. A new attempt without verification may create a duplicate payment.

Next steps

• See the card payment endpoint
• Configure tokenization
• Create an installment payment
• Configure Webhooks
• Understand refunds
• Understand chargebacks