Authentication: OAuth2 Bearer Token

To securely access dLocal's Payouts API, you must first obtain an access token using the OAuth2 Client Credentials flow. This token should then be included in the Authorization header of all subsequent API requests as a Bearer token.

Step 1: Get a Bearer Token

Merchants must request an access token using the client credentials flow.

Endpoint

URL Selector with Opacity

Post

Production URL

Example request

curl --location 'https://api.dlocal.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "client_credentials",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}"
}'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjBlNGY1NTUxLWRlNDYt...",
  "scope": "payouts",
  "expires_in": 180,
  "token_type": "Bearer"
}

Request params

Name	Description
`grant_type`	The `grant_type` parameter must be set to `client_credentials`.
`client_id`	Your merchant's Client ID. Your assigned Technical Account Manager will provide this value.
`client_secret`	Your merchant's Client Secret. Your assigned Technical Account Manager will provide this value.

To get your credentials, please contact your designated Technical Account Manager or email us at [email protected] to request setup.

Response params

Name	Description
`access_token`	The access token string issued by dLocal.
`scope`	A list with the permissions that the merchant can access.
`expires_in`	The duration (in seconds) for which the access token is valid.
`token_type`	The type of token, which will always be `"Bearer"`.

Step 2: Authenticate subsequent API requests

After successfully obtaining your access_token through the /oauth/token endpoint, you must include it in the Authorization header of all your subsequent API requests to dLocal's Payouts API v3. This ensures that your requests are authenticated and authorized.

Authorization header

curl -X POST \
-H 'X-Date: {X-Date}' \
-H 'X-Version: 3.0' \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBlNGY1NTUxLWRlNDYt..." \
-d '{body}'
 https://api.dlocal.com/payouts/v3

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Important considerations

Expiration. Access tokens have a limited lifespan, indicated by the expires_in attribute in the token response. You must implement a mechanism to refresh your token before it expires to avoid authentication errors.
Security. Always keep your client_id and client_secret confidential. Do not expose them in client-side code or public repositories.
Error handling. If your access token is invalid or expired, the API will return an HTTP 403 Forbidden error with an appropriate error code. Ensure your application handles these errors by requesting a new token.