Customer registration

Before creating a payment or subscription, register the payer as a customer in Asaas.

Once creation is complete, the API returns a unique identifier, such as cus_000005219613. Store this ID in your application to use it in future payments, subscriptions, queries, and updates.

When to use

Create a customer when your integration needs to register a payer in order to:

• create payments;
• create subscriptions;
• reuse registration data in future operations;
• query or update payer information;
• link the Asaas record to the customer in your system.

If the customer has already been registered, reuse the ID stored by your application or look up existing customers before creating a new record.

Before you start

Define:

• which customer data will be sent;
• which identifier from your system will be provided in externalReference;
• whether the customer will receive notifications from Asaas;
• where the returned ID will be stored;
• how your integration will prevent duplicate records.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Receive the payer details"] --> B{"Does the customer already have an ID in Asaas?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BSim --> C["Reuse the stored ID"]
    BNao --> D["Look up or register the customer"]
    D --> E["Store the returned ID"]

    C --> F["Link the ID to the internal record"]
    E --> F

    F --> G["Create a payment using the customer field"]
    G --> H["Track 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 correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

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

    class BSim respostaSim
    class BNao respostaNao

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

1. Check whether the customer already exists

Before creating a record, check whether your application already has the customer's ID in Asaas.

When necessary, look up existing customers using the endpoint:

List customers

This check is especially important in flows with:

• automatic retries;
• order reprocessing;
• asynchronous queues;
• customers received through different channels;
• operations that may be executed more than once.

2. Create the customer

Send a request to:

POST /v3/customers

See the endpoint: Create new customer.

Request example

{
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792",
  "mobilePhone": "4799376637"
}

Important fields

See the endpoint reference to check all accepted fields, formats, and validation rules.

3. Store the returned ID

After creating the customer, the API returns the registered data and the resource identifier.

Simplified response example

{
  "id": "cus_000005219613",
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792"
}

Store the value returned in id.

This identifier must be sent in the customer field when creating a payment or subscription for the customer.

Example:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 100,
  "dueDate": "2026-08-15"
}

See the endpoint: Create new payment.

Avoid duplicate customers

A recommended strategy is:

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Receive the payer details"] --> B["Check the link saved in the application"]
    B --> C{"Does the customer already have an ID?"}

    C --> CSim(("Yes"))
    C --> CNao(("No"))

    CSim --> D["Reuse the ID"]
    CNao --> E["Look up or create the customer"]
    E --> F["Store the returned ID"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

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

    class CSim respostaSim
    class CNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#EF4444,stroke-width:4px

Do not create a new customer for each payment from the same payer.

Confirm the result

After the request, confirm that:

• the response returned the id field;
• the data was registered correctly;
• the ID was stored by your application;
• the record was linked to the customer in your system;
• the notification settings match the desired journey.

If the customer is not created

Check whether:

• the data is in the expected format;
• the CPF or CNPJ was provided correctly;
• the email and phone number are valid;
• the URL and the API key belong to the same environment;
• all required fields were sent;
• the customer was not created in a previous attempt.

Best practices

• Store the ID returned by the API.
• Use externalReference to make reconciliation easier.
• Validate CPF or CNPJ, email, and phone number before sending.
• Reuse the customer in subsequent payments and subscriptions.
• Do not rely only on CPF, CNPJ, or email as the internal link.
• Record the relationship between the Asaas ID and your application's ID.
• Review the notification settings to avoid duplicate communications.

API reference

Next steps

• Learn about the payments flow
• Create a new payment
• Create payments via bank slip
• Create payments via Pix
• Create payments via credit card
• Configure notifications
• Configure Webhooks