Create and track payments

Payments record amounts receivable in the Asaas account and make payment methods available to your customers.

In this flow, your integration registers the customer, creates the payment, makes the payment available, and tracks its status through reconciliation.

When to use

Use payments when your integration needs to generate an amount receivable for a customer registered in Asaas.

Some common scenarios are:

• one-off sales;
• billing for services rendered;
• monthly fees controlled by your application;
• transparent checkout;
• sending a hosted invoice;
• receiving payments by bank slip (boleto), Pix, or credit card.

To provide a page where the customer fills in their own details or chooses products and payment terms, see:

• Payment Link
• Asaas Checkout

Before you start

To create a payment:

1. register or look up the customer;
2. store the ID returned in the id field;
3. define the payment method;
4. define the amount;
5. provide the due date;
6. prepare status tracking.

The customer ID must be sent in the customer field when creating the payment.

How it works

Create or look up the customer
↓
Store the customer ID
↓
Create the payment
↓
Make the payment available
↓
Track the status
↓
Reconcile in the source system

1. Register the customer

Before creating the payment, register the payer and store the ID returned by the API.

See the guide: Customer registration.

2. Create the payment

Send a request to the payment creation endpoint.

The main fields are:

See the endpoint: Create new payment.

After creation, store the payment ID returned by the API. It will be needed for queries, updates, refunds, and reconciliation.

3. Choose the payment method

The payment's behavior depends on the value sent in billingType.

See the corresponding guide:

• Payments via bank slip (boleto)
• Payments via Pix
• Payments via credit card

To let the customer choose the payment method on the Invoice, use the corresponding setting provided by the endpoint.

To split the amount into installments, see Create an installment payment.

4. Make the payment available

After creating the payment, your application can:

• use the returned URL to display the Invoice;
• send the Invoice to the customer;
• present the bank slip, Pix QR Code, or card form within your own flow;
• use a Payment Link;
• use Asaas Checkout.

To redirect the customer back to your application after payment, see Redirection after payment.

5. Track the status

After creation, track the payment to identify events such as:

• payment awaiting payment;
• payment confirmed or received;
• overdue payment;
• payment deleted or restored;
• refund;
• chargeback;
• card processing failure.

Use Webhooks to automatically receive changes that occur in the account.

To learn about the events related to the payment lifecycle, see Events for payments.

6. Reconcile the payment

When you receive an update:

1. identify the payment by the id field;
2. find the corresponding record in your system;
3. validate the new status;
4. update the order, service, or internal balance;
5. record the processing date and result.

Use externalReference to link the payment to an order, contract, or record in your application.

Implement idempotency to prevent the same event from being processed more than once.

Configure notifications

Asaas can send payment-related notifications through channels such as email, SMS, or WhatsApp, depending on availability and account settings.

Notifications may include:

1. notice of payment creation;
2. reminder before the due date;
3. notice on the due date;
4. overdue notice;
5. reminders after the due date;
6. update notice;
7. sending of the bank slip digitable line.

See the Notifications guide.

Important considerations

• Store the customer and payment IDs.
• Use externalReference to make reconciliation easier.
• Validate the customer, amount, and due date before creation.
• Avoid duplicate payments on retries and reprocessing.
• Implement idempotency when processing Webhooks.
• Handle card failures and declines.
• Consider the due date and expiration rules for bank slips and Pix.
• Do not treat a created payment as a paid payment.
• Query the operation again when there is a timeout or an inconclusive response before repeating the creation.

Next steps

• Register a customer
• Create payments via bank slip
• Create payments via Pix
• Create payments via credit card
• Create an installment payment
• Configure redirection after payment
• Configure Webhooks
• Configure notifications
• Learn about the refund process
• Understand the chargeback flow