Create a Payment Link

Create a Payment Link to provide a page hosted by Asaas and generate charges from the details entered by the payer.

The same link can be used for one-time, installment or recurring charges.

Before you start

Define:

• the charge type;
• the available payment methods;
• the amount, when fixed;
• the specific installment or recurrence rules;
• whether customers created through the link will receive notifications.

You don't need to register the customer before making the link available. The customer record is created when the payer finishes filling in the form and the charge is generated.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Define the charge type"] --> B["Create the Payment Link"]
    B --> C["Share the link"]
    C --> D["Payer enters their details"]
    D --> E["Asaas generates the charge"]
    E --> F["Receive the Webhooks"]
    F --> G["Reconcile the payment"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

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

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Choose the charge type

The chargeType field defines the link's behavior:

If value is not provided, the payer can define the amount at the time of payment.

See the Create a payment link endpoint.

2. Create the Payment Link

Use:

POST /v3/paymentLinks

One-time charge

Use chargeType = DETACHED to generate a new charge each time the link is filled in.

{
  "name": "Book sale",
  "description": "Any book for only R$: 50.00",
  "value": 50.00,
  "billingType": "UNDEFINED",
  "chargeType": "DETACHED",
  "dueDateLimitDays": 10
}

With billingType = UNDEFINED, the payer can choose among the available payment methods.

Whenever the link allows payment via bank slip (boleto), provide dueDateLimitDays. This field defines how many business days the bank slip can be paid after it is generated.

The link remains active for new payments until it is disabled or removed.

Installment charge

Use chargeType = INSTALLMENT and set the maximum number of installments in maxInstallmentCount.

{
  "billingType": "CREDIT_CARD",
  "chargeType": "INSTALLMENT",
  "name": "Electronics sale",
  "description": "Any product in up to 10x of R$ 50.00",
  "value": 500.00,
  "maxInstallmentCount": 10,
  "notificationEnabled": false
}

In this example, the payer can choose up to 10 installments.

Since the link only accepts credit card, dueDateLimitDays is not required.

notificationEnabled = false disables notifications for customers registered through this link. If the field is not provided, the default value is true.

See Notifications.

Recurring charge

Use chargeType = RECURRENT so that filling in the link creates a subscription.

{
  "billingType": "CREDIT_CARD",
  "chargeType": "RECURRENT",
  "name": "Book subscription",
  "description": "Get a book every month for R$: 50.00",
  "value": 50.00,
  "subscriptionCycle": "MONTHLY"
}

In this flow, subscriptionCycle defines the subscription cycle.

The other accepted values are available in the Payment Link creation reference.

Expected result

With a valid request, the API returns HTTP 200 and the Payment Link can be made available to the payer.

Store the link identifier for future queries, updates and image uploads.

3. Track the generated charges

Charges created by the Payment Link follow the normal payment event flow.

In the Webhook payload:

• paymentLink identifies the Payment Link that originated the charge;
• customer identifies the customer created when the form was filled in.

See Payment events.

If you need to retrieve the data of the generated customer, use:

See the Retrieve a single customer endpoint.

4. Add images

You can add up to 5 images to the Payment Link.

Use:

POST /v3/paymentLinks/{id}/images

Send the file with:

Content-Type: multipart/form-data

To set the uploaded image as the main one, provide:

main = true

See the Add an image to a payment link endpoint.

Next steps

• Track Payment events
• Update a Payment Link
• Add images to the Payment Link
• List Payment Links
• Configure Notifications
• See the API limits