DiscordStatus
Guias / Guides

Java

Java software development kit for the API

Integrate Asaas with the Java SDK

Use the official Asaas SDK to integrate Java or Kotlin applications with the API using the library's own services and models.

📘

The Asaas Java SDK is the most practical, secure, and robust way to integrate the REST API into applications built with Java or Kotlin. It is officially published on Sonatype (Maven Central) and continuously validated by quality and security tools.

Before you start

You need:

  • Java >= 1.8;
  • an Asaas account in Sandbox or Production;
  • an API Key for the environment you are using.

During development, use Sandbox.

1. Install the SDK

The SDK uses:

groupId: com.asaas
artifactId: api-sdk

The current published version is 1.0.3.

Maven

<dependency>
    <groupId>com.asaas</groupId>
    <artifactId>api-sdk</artifactId>
    <version>1.0.3</version>
</dependency>

Gradle

implementation group: 'com.asaas', name: 'api-sdk', version: '1.0.3'
📌

Check the GitHub or the Sonatype page to find the latest version.

2. Configure the API Key

Initialize the SDK with the account credential:

import com.asaas.apisdk.AsaasSdk;
import com.asaas.apisdk.config.ApiKeyAuthConfig;
import com.asaas.apisdk.config.AsaasSdkConfig;

ApiKeyAuthConfig authConfig = ApiKeyAuthConfig.builder()
    .apiKey("YOUR_API_KEY")
    .apiKeyHeader("access_token")
    .build();

AsaasSdkConfig config = AsaasSdkConfig.builder()
    .apiKeyAuthConfig(authConfig)
    .build();

AsaasSdk asaasSdk = new AsaasSdk(config);
❗️

Never expose your API key directly in the source code. Use environment variables or a secure configuration manager

See how API authentication works.

3. Select the environment

The SDK provides:

Environment.DEFAULT      // Production
Environment.PRODUCTION   // Production
Environment.SANDBOX      // Sandbox

Set the environment after initializing the client:

import com.asaas.apisdk.http.Environment;

asaasSdk.setEnvironment(Environment.SANDBOX);

The API Key must belong to the same environment used by the SDK.

4. Configure the timeout, if needed

The timeout for HTTP requests can be set in milliseconds:

AsaasSdkConfig config = AsaasSdkConfig.builder()
    .timeout(10000)
    .apiKeyAuthConfig(authConfig)
    .build();

AsaasSdk asaasSdk = new AsaasSdk(config);

5. Use the SDK services

API resources are organized into services.

For example, to create a customer, use CustomerService:

import com.asaas.apisdk.models.CustomerGetResponseDto;
import com.asaas.apisdk.models.CustomerSaveRequestDto;
import com.asaas.apisdk.services.CustomerService;

CustomerService customerService = asaasSdk.customer;

CustomerSaveRequestDto request = CustomerSaveRequestDto.builder()
    .name("John Doe")
    .cpfCnpj("24971563792")
    .email("[email protected]")
    .phone("88888888888")
    .build();

CustomerGetResponseDto customer = customerService.createNewCustomer(request);

Expected result

The operation returns a CustomerGetResponseDto with the data of the created customer.

Store the returned identifier when it is needed for the next operations in your integration.

See the services documentation in the official SDK repository.

Use the SDK with Spring Boot

Register the client and the required services as beans.

import com.asaas.apisdk.AsaasSdk;
import com.asaas.apisdk.config.ApiKeyAuthConfig;
import com.asaas.apisdk.config.AsaasSdkConfig;
import com.asaas.apisdk.http.Environment;
import com.asaas.apisdk.services.CustomerService;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AsaasConfig {

    @Value("${asaas.api.key}")
    private String asaasApiKey;

    @Bean
    public AsaasSdk asaasSdk() {
        ApiKeyAuthConfig authConfig = ApiKeyAuthConfig.builder()
            .apiKey(asaasApiKey)
            .apiKeyHeader("access_token")
            .build();

        AsaasSdkConfig config = AsaasSdkConfig.builder()
            .apiKeyAuthConfig(authConfig)
            .build();

        AsaasSdk asaasSdk = new AsaasSdk(config);
        asaasSdk.setEnvironment(Environment.SANDBOX);

        return asaasSdk;
    }

    @Bean
    public CustomerService customerService(AsaasSdk asaasSdk) {
        return asaasSdk.customer;
    }
}

Then inject the service into the component that will run the operation:

import com.asaas.apisdk.models.CustomerGetResponseDto;
import com.asaas.apisdk.models.CustomerSaveRequestDto;
import com.asaas.apisdk.services.CustomerService;

import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class MyService {

    private final CustomerService customerService;

    public CustomerGetResponseDto save() {
        CustomerSaveRequestDto request = CustomerSaveRequestDto.builder()
            .name("John Doe")
            .cpfCnpj("24971563792")
            .email("[email protected]")
            .phone("88888888888")
            .build();

        return customerService.createNewCustomer(request);
    }
}
✅

With this structure, the SDK is fully integrated into your Spring application. Just repeat the pattern for other services such as payments, subscriptions, payment links, etc.

You can find more examples by clicking here

Source code and distribution

The SDK is distributed through Maven Central.

You can also check the official repository for:

Next steps

Updated 1 day ago

Did this page help you?