Endpoint responsible for paying an existing charge by credit card at the time of the call.

Unlike direct charge creation with credit card, this endpoint is used when the charge already exists and the payment will be informed later, with card data or with a previously generated token.

When to use

Use this endpoint when your integration already has a charge created in Asaas and needs to process the payment by credit card later.

Some common scenarios include:

• charge created without card data at the initial moment;
• charge created for later payment by the customer;
• payment attempt for an existing charge;
• use of a tokenized card to pay an open charge;
• manual or operational reprocessing of a charge that has not yet been paid;
• flow in which the application collects card data after the charge is created;
• integration that separates charge creation from payment data capture.

When not to use

Do not use this endpoint to:

• create a new charge;
• create a charge already paid by card at the same time;
• schedule future payment by card;
• pay a charge that has already been paid;
• pay a removed charge;
• refund a charge;
• update customer registration data;
• create or update a card token without paying the charge;
• change the payment method of a charge that is not eligible for payment by card.

If the intention is to create a charge and process the card in the same request, use the charge creation endpoint with credit card.

If the intention is only to generate a token for future use, use the credit card tokenization endpoint.

Recommended flow

In a typical integration, this endpoint is part of the following flow:

Create or locate the customer
↓
Create a charge in Asaas
↓
Store the charge id
↓
Collect card data or retrieve a creditCardToken
↓
Send the charge payment request
↓
Receive the processing result
↓
Consult the charge, if necessary
↓
Update the status in the source system

Prerequisites

Before using this endpoint, validate whether:

• the charge already exists in Asaas;
• the charge id was stored correctly;
• the charge belongs to the authenticated account;
• the charge is in a state that allows a payment attempt;
• the charge has not yet been paid;
• the charge has not been removed;
• the API Key belongs to the correct environment, Sandbox or Production;
• the application has authorization to process card payments;
• the card data was collected securely;
• the card token, when used, belongs to the correct customer.

Request parameter

This endpoint uses the charge identifier in the request path.

Identifier example:

pay_123456789

The id must correspond to an existing charge in the authenticated Asaas account.

Main body parameters

The request can be made in two ways:

• informing the complete card and cardholder data;
• informing a previously generated creditCardToken.

Card data

When not using a token, send the creditCard object with the card data.

Common object fields:

Example:

{
  "creditCard": {
    "holderName": "Marcelo H Almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2028",
    "ccv": "318"
  }
}

Cardholder data

When not using a token, also send the creditCardHolderInfo object with the cardholder data.

Common object fields:

Example:

{
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  }
}

Use of tokenized card

The creditCardToken allows paying a charge without resending all card and cardholder data.

Example:

{
  "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
}

When using a token, consider that:

• the token must have been generated previously;
• the token must be associated with the correct customer;
• the token must not be used for transactions of another customer;
• the use of the token reduces the exposure of sensitive data;
• invalid, expired, or incompatible tokens may generate an error in the payment attempt.

Request example with card data

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/payWithCreditCard \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "creditCard": {
      "holderName": "Marcelo H Almeida",
      "number": "5162306219378829",
      "expiryMonth": "05",
      "expiryYear": "2028",
      "ccv": "318"
    },
    "creditCardHolderInfo": {
      "name": "Marcelo Henrique Almeida",
      "email": "[email protected]",
      "cpfCnpj": "24971563792",
      "postalCode": "89223005",
      "addressNumber": "277",
      "addressComplement": null,
      "phone": "4738010919",
      "mobilePhone": "47998781877"
    }
  }'

Request example with token

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/payWithCreditCard \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
  }'

Expected return

In case of success, the API returns 200 OK with the updated charge data.

Illustrative return example:

{
  "object": "payment",
  "id": "pay_123456789",
  "billingType": "CREDIT_CARD",
  "status": "CONFIRMED",
  "value": 100.00,
  "netValue": 97.00,
  "customer": "cus_000005219613",
  "creditCard": {
    "creditCardNumber": "8829",
    "creditCardBrand": "MASTERCARD",
    "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
  }
}

Immediate processing

This endpoint tries to process the payment at the time of the call.

This means that:

• the transaction is sent for validation at the time of the request;
• the API return indicates the result known at that moment;
• the payment may be approved or refused;
• validation failures may return an error;
• there is no future payment scheduling;
• the charge due date does not turn this call into a scheduled payment.

Important behaviors

When using this endpoint, consider that:

• the charge must already exist before the call;
• the operation tries to pay the charge at the time of the request;
• the endpoint does not create a new charge;
• the endpoint does not schedule future payment;
• the endpoint should not be treated as idempotent;
• the endpoint may return an error if the charge is in an incompatible state;
• the endpoint may return an error if the card is refused;
• the endpoint may return an error if the token does not belong to the correct customer;
• approved payment changes the state of the charge;
• the integration must consult the charge before trying again after timeout or uncertain error.

Idempotency, timeout, and retries

Do not treat this endpoint as an idempotent operation.

Because the call processes a real payment attempt, an automatic retry without validation may generate undesired behavior, especially in timeout or response loss scenarios.

Recommendations:

• configure sufficient timeout to wait for processing;
• avoid very short timeouts;
• in case of timeout, consult the charge before trying again;
• do not automatically repeat the call without checking the current status;
• internally register the payment attempt;
• use internal identifiers to reconcile attempts and returns;
• handle card refusal errors without indefinite immediate retry.

Recommended flow in case of timeout:

Send payment attempt
↓
Timeout or inconclusive response
↓
Consult the charge by id
↓
Check current status
↓
If it is still open, evaluate a new attempt
↓
If it is paid or confirmed, update source system

Important business rules

Before implementing this endpoint, consider the following rules:

• the charge must exist in Asaas;
• the charge must belong to the authenticated account;
• the charge must be in a state compatible with payment;
• the charge must not be removed;
• the charge must not be paid;
• the request must be authenticated with a valid API Key;
• inform creditCard and creditCardHolderInfo when not using a token;
• inform creditCardToken when opting for tokenized card;
• do not send complete card data when the token is sufficient;
• the token must be linked to the correct customer;
• the payment is processed immediately;
• refused payments must be handled according to the API response;
• refunds must be made through their own flow, not through this endpoint.

Dependencies with other resources

This endpoint depends on resources and previous states of the charge flow.

Operational impacts

The use of this endpoint can directly impact the financial and operational flow of the integration.

Some important impacts:

• payment is attempted immediately;
• an approved transaction changes the charge status;
• a refused transaction may require a new attempt with another card or guidance to the customer;
• retries without prior consultation may cause operational duplication or inconsistency;
• timeouts may leave the application without knowing the real result of the attempt;
• payment failures must be reflected in the source system;
• financial reconciliation must consider the updated charge status;
• tokens must be treated as sensitive data and used only for the correct customer;
• charges paid by card may be subject to refund, dispute, or later analysis, according to the card flow.

Error handling

Some common errors when using this endpoint include:

Security

When working with card payments, adopt additional security precautions.

Recommendations:

• use HTTPS throughout the card data capture flow;
• do not store the full card number;
• do not store the security code;
• do not send card data to logs, support tools, or monitoring systems;
• prefer tokenization when there are future payments for the same customer;
• restrict internal access to payment payloads;
• mask sensitive data in errors, logs, and administrative screens;
• validate whether the application is prepared to handle card refusals and failures.

Best practices

For a safer implementation, it is recommended to:

• create the charge before calling this endpoint;
• store the charge id in the source system;
• consult the charge before attempting payment;
• use creditCardToken whenever possible;
• do not send creditCard, creditCardHolderInfo, and creditCardToken at the same time unnecessarily;
• validate cardholder data before the call;
• configure an adequate minimum timeout for processing;
• consult the charge before performing retries;
• register each payment attempt in the source system;
• reflect the attempt result in the internal status;
• test approval, refusal, and timeout scenarios in Sandbox before operating in Production.

Sandbox precautions

In Sandbox, use this endpoint to validate the main card payment scenarios.

During tests, it is recommended to validate:

• payment with complete card data;
• payment with creditCardToken;
• attempt with nonexistent charge;
• attempt with charge already paid;
• attempt with refused card;
• attempt with invalid token;
• behavior in case of timeout;
• status update in the source system;
• charge consultation after the API return.

Related content

See also:

• Create new charge;
• Create charge with credit card;
• Charges via credit card;
• Credit card tokenization;
• Retrieve a single charge;
• Retrieve status of a charge;
• Refund charge;
• Webhooks for charges;
• Testing credit card payment.