DiscordStatus
Guias / Guides

Payments via credit card

Suggest Edits

Asaas accepts a variety of card brands easily and without a monthly fee. You can make sales in cash, in installments, and recurrently.

Creating a payment by credit card

There are two steps you can follow; one is to create a credit card type payment and redirect the user to the invoice screen to make the payment.

POST /v3/payments
Check the complete reference of this endpoint

{
      "customer": "cus_000005219613",
      "billingType": "CREDIT_CARD",
      "value": 109.90,
      "dueDate": "2023-07-21"
}

When creating a payment with credit card payment, you redirect the customer to the invoice URL (invoiceUrl) so they can enter their card details through Asaas's interface.

Is it possible to generate a payment that accepts a debit card?

Sending card details through the API is not possible for debit cards.

However, you can send the customer to the invoiceUrl as described above. If the billingType is CREDIT_CARD or UNDEFINED, the debit card option will be enabled on the invoice.

Creating a payment with a credit card and pay it in the same action

The second step is to send the credit card details at the time of creating the payment, allowing for the payment to be processed immediately upon payment creation.

To do this, simply send the credit card details along with the holder's information through the creditCard and creditCardHolderInfo objects when making the payment creation request. It's important that the holder's information exactly matches that registered with the card's issuing bank; otherwise, the transaction may be denied due to suspected fraud.

If the transaction is authorized, the payment will be created, and the API will return HTTP 200. Otherwise, the payment will not be persisted, and HTTP 400 will be returned.

If you are in Sandbox, you can use test credit card numbers.

POST /v3/payments
Check the complete reference of this endpoint

{
      "customer": "cus_000005219613",
      "billingType": "CREDIT_CARD",
      "value": 100.00,
      "dueDate": "2023-07-21",
      "creditCard": {
        "holderName": "marcelo h almeida",
        "number": "5162306219378829",
        "expiryMonth": "05",
        "expiryYear": "2024",
        "ccv": "318"
      },
      "creditCardHolderInfo": {
        "name": "Marcelo Henrique Almeida",
        "email": "marcelo.almeida@gmail.com",
        "cpfCnpj": "24971563792",
        "postalCode": "89223-005",
        "addressNumber": "277",
        "addressComplement": null,
        "phone": "4738010919",
        "mobilePhone": "47998781877"
      },
      "remoteIp": "116.213.42.532"
}

📘
  • Regardless of the due date entered, the capture (charge to the customer's card) will be made when the charge is created.

  • If you choose to capture customer card data in your system interface, the use of SSL (HTTPS) is mandatory, otherwise your account may be blocked for credit card transactions.
  • To avoid timeouts and resulting duplicates in capture, we recommend configuring a minimum timeout of 60 seconds for this request.

Credit card tokenization

After the first transaction for the customer with a credit card, the API response will return the attribute creditCardToken.

With this information, in subsequent transactions, the creditCardToken attribute can replace the creditCard and creditCardHolderInfo objects and be directly informed at the root of the request, thus not requiring the objects to be informed again.

POST /v3/payments
Check the complete reference of this endpoint

{
      "customer": "cus_000005219613",
      "billingType": "CREDIT_CARD",
      "value": 100.00,
      "dueDate": "2023-07-21",
      "creditCardToken": "76496073-536f-4835-80db-c45d00f33695",
      "remoteIp": "116.213.42.532"
}

You can also create a token at any time. Having the customer's data, just send it to the tokenization endpoint, and you will receive the creditCardToken.

POST /v3/creditCard/tokenize
Check the complete reference of this endpoint

{
      "customer": "cus_000005219613",
      "creditCard": {
        "holderName": "marcelo h almeida",
        "number": "5162306219378829",
        "expiryMonth": "05",
        "expiryYear": "2024",
        "ccv": "318"
      },
      "creditCardHolderInfo": {
        "name": "Marcelo Henrique Almeida",
        "email": "marcelo.almeida@gmail.com",
        "cpfCnpj": "24971563792",
        "postalCode": "89223-005",
        "addressNumber": "277",
        "addressComplement": null,
        "phone": "4738010919",
        "mobilePhone": "47998781877"
      },
      "remoteIp": "116.213.42.532"
}

The API will return to you the last 4 digits of the card creditCardNumber and the card brand creditCardBrand (in case you want to display it on the screen, for example), in addition to the creditCardToken.

This functionality is useful if you develop a "Save payment data" feature in your application.

🚧

  • The tokenization functionality is previously enabled in Sandbox and you can now test it. For production use, you must request the functionality to be enabled from your account manager. Enabling the functionality is subject to prior analysis and may be approved or denied according to the risks of the operation.
  • The token is stored per client and cannot be used in transactions by other clients.

Installment by card

You can also easily create an installment charge directly to the customer's credit card.

POST /v3/payments
Check the complete reference of this endpoint


{
  "customer": "cus_000005219613",
  "billingType": "CREDIT_CARD",
  "value": 2000.00,
  "dueDate": "2023-07-21",
  "installmentCount": 10,
  "installmentValue": 200,
  "creditCard": {
      "holderName": "marcelo h almeida",
      "number": "5162306219378829",
      "expiryMonth": "05",
      "expiryYear": "2024",
      "ccv": "318"
    },
    "creditCardHolderInfo": {
      "name": "Marcelo Henrique Almeida",
      "email": "marcelo.almeida@gmail.com",
      "cpfCnpj": "24971563792",
      "postalCode": "89223-005",
      "addressNumber": "277",
      "addressComplement": null,
      "phone": "4738010919",
      "mobilePhone": "47998781877"
    },
    "remoteIp": "116.213.42.532"
}

🚧

Attention

  • It is allowed to create credit card installments in up to 21 installments for Visa and Master cards.
    Previously, installments of up to 12 installments were supported for all brands.
    For other brands, except Visa and Master, the limit continues to be 12 installments.

❗️

Important

For single charges (1x), you should not use the installment attributes: installmentCount, installmentValue and totalValue. If it is a 1x charge, only value is used.

Only charges with 2 or more installments use the installment attributes.

Return of errors for payments and credit card tokenization.

By default, if there is nothing wrong with the card details entered and there is a problem with the transaction, the API will return a generic error to you.

{
    "errors": [
        {
            "code": "invalid_creditCard",
            "description": "Unauthorized transaction. Please check your credit card details and try again."
        }
    ]
}

We do this for security reasons so that people with bad intentions do not use Asaas to test lost credit cards

🚧

You can access the real error that transactions present by asking your account manager for this functionality to be enabled. A prior analysis will be carried out before release. The recommendation is that this real error is never shown to the end user.


API Reference

📘

Check the complete reference of the Payments endpoint (/v3/payments)

Access our API reference

Updated 10 days ago