Use API credentials to authenticate your integration with dLocal API.

API credentials are required for all requests in both sandbox and live environments and are managed through the Merchant Dashboard. You must have the Developer or Admin role to access this section.

API credentials overview

Key types

Each API Credential set consists of three keys:

In addition, a separate key is used if your integration includes Smart Fields tokenization.

❗️

All credentials must be securely stored. Keys cannot be retrieved after creation.

Environments

Credentials are environment-specific. You can create:

• Sandbox credentials for testing and development.
• Live credentials for production use.

During key creation, use the environment toggle to ensure credentials are generated in the appropriate context. Keys created for one environment will not function in the other.

Scope

When generating a credential, all scopes are selected by default. However, you can customize this selection based on your needs:

• Payins. For processing incoming payments.
• Payouts. For executing outgoing transfers.
• Both. For full access.

This option is only available when multiple products are enabled on your account.

Status

Each API Credential set includes a status indicating its current usability:

Create API Credentials

New credentials are created through the Integration > API Credentials section in the Merchant Dashboard. The environment in which the credentials will be created depends on the position of the environment toggle at the time of creation.

If the toggle is set to Test mode, the credentials will only work in the sandbox environment. Otherwise, the credentials will be generated for production use.

To generate a new key:

1. Navigate to Integration > API Credentials in the Merchant Dashboard.
2. Ensure the environment toggle is set correctly (Sandbox or Live).
3. Click + Create credential.
4. Select the scope: Payins, Payouts, or both.
5. (Optional) Provide a description for internal reference (e.g., service name or use case).
6. Confirm that the credentials will be stored securely.

After creation, the x-login, x-trans-key, and Secret keywill be shown once. These credentials will not be accessible again after this point. Store them securely using a credential or secrets management solution.

Manage credentials

You can perform two actions on existing credentials:

Rotate key

Credential rotation should be part of your regular deployment or key management lifecycle.
Recommended rotation process:

1. Generate new keys and retrieve values securely. To rotate:
   1. Open the options menu (⋮) next to the credential.
   2. Select Roll credentials. If this credential is the only one currently active in this scope, you won’t be able to set an expiration of less than 7 days.
   3. Set the expiration time for the old credential.
   4. Confirm your action. This action is irreversible.
2. Configure applications to accept both old and new keys during the overlap period.
3. Monitor logs to confirm that successful requests are made using the new key.
4. Allow the old credential to expire or delete it manually after validation.

Once rotated, the old credential will enter an Inactive state and will be permanently removed after 30 days.

Delete key

This is commonly used when deprecating services or endpoints. You can delete any credential except when it's the only active one for its scope.

To remove credentials that are no longer in use:

1. Confirm the key is not the only active one for its scope.
2. Validate that it has been used at least once (for live keys).
3. Delete and allow the 24-hour deactivation window to complete. To delete:
   1. Open the options menu (⋮) next to the credential.
   2. Select Delete key.
   3. Confirm your action. This action is irreversible.

Once deleted, the key will enter an Inactive state and be permanently removed after 30 days.

❗️

Deleted credentials cannot be restored, and any systems using them will lose access.

---

Explore the Integration section

Go to the Merchant Dashboard and navigate to Account Management > Developers > Integration.

Hover over the hotspots to learn about key sections of the interface and how to use them.