Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mercadopago/sdk-java/llms.txt

Use this file to discover all available pages before exploring further.

OauthClient implements Mercado Pago’s OAuth 2.0 authorization code flow, which is the standard mechanism for marketplace and platform integrations to act on behalf of a seller. In this flow, the marketplace generates an authorization URL that the seller visits to grant permission. After authorization, Mercado Pago redirects the seller back with a one-time authorization_code that the marketplace exchanges for an access_token and refresh_token. The access_token is subsequently passed via MPRequestOptions to all API calls that must run with the seller’s identity (e.g., creating a split payment on their behalf). The refresh_token must be exchanged for a new access_token before the current one expires.

​
OauthClient

Package: com.mercadopago.client.oauth

​
Constructors

// Uses the default HTTP client configured in MercadoPagoConfig
OauthClient()

// Supply a custom MPHttpClient (useful for testing or proxy scenarios)
OauthClient(MPHttpClient httpClient)

​
Methods

​
getAuthorizationURL

Builds the OAuth authorization URL that the seller must visit to grant your marketplace access to their account. Internally calls UserClient.get() to determine the authenticated user’s country and constructs the correct country-specific authorization host. 
String getAuthorizationURL(String appId, String redirectUri)
    throws MPException, MPApiException

String getAuthorizationURL(String appId, String redirectUri, MPRequestOptions requestOptions)
    throws MPException, MPApiException
​
appId
String
required
Your application ID (client_id) registered in the Mercado Pago developer panel.
​
redirectUri
String
required
The URL to which Mercado Pago will redirect the seller after they grant (or deny) access. Must match the redirect URI configured in your application settings.
​
requestOptions
MPRequestOptions
Optional per-request overrides for access token, headers, or timeouts. Pass null to use defaults.
Returns: String — the full country-specific authorization URL. Returns null if the authenticated user’s country cannot be determined.

​
createCredential

Exchanges an authorization code for OAuth credentials (access token, refresh token, and expiration). Call this after the seller is redirected back to your redirectUri with the code query parameter. 
CreateOauthCredential createCredential(String authorizationCode, String redirectUri)
    throws MPException, MPApiException

CreateOauthCredential createCredential(String authorizationCode, String redirectUri, MPRequestOptions requestOptions)
    throws MPException, MPApiException
​
authorizationCode
String
required
The one-time authorization code received as the code query parameter on your redirect URI after the seller grants access.
​
redirectUri
String
required
The same redirect URI used when generating the authorization URL. Must match exactly.
​
requestOptions
MPRequestOptions
Optional per-request overrides. The clientSecret used internally is taken from requestOptions.getAccessToken() if provided, or from MercadoPagoConfig.getAccessToken() otherwise.
Returns: CreateOauthCredential — contains the seller’s access_token, refresh_token, token_type, expires_in, and scope.

​
refreshCredential

Refreshes an expired OAuth access token using the seller’s refresh_token. Access tokens expire after a fixed period — call this proactively before the token expires to maintain uninterrupted API access on behalf of the seller. 
RefreshOauthCredential refreshCredential(String refreshToken)
    throws MPException, MPApiException

RefreshOauthCredential refreshCredential(String refreshToken, MPRequestOptions requestOptions)
    throws MPException, MPApiException
​
refreshToken
String
required
The refresh token returned during the initial createCredential call.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: RefreshOauthCredential — contains a new access_token, refresh_token, and expiration details.

​
CreateOauthCredentialRequest fields

This request DTO is built internally by createCredential. Its fields are:
​
grantType
String
Fixed value: "authorization_code". Set automatically by the SDK.
​
clientSecret
String
Your marketplace’s access token, used as the client_secret. Set automatically from MercadoPagoConfig or requestOptions.
​
clientId
String
Your application ID (client_id).
​
code
String
The authorization code received from the redirect.
​
redirectUri
String
The redirect URI used during authorization.

​
RefreshOauthCredentialRequest fields

This request DTO is built internally by refreshCredential. Its fields are:
​
grantType
String
Fixed value: "refresh_token". Set automatically by the SDK.
​
clientSecret
String
Your marketplace’s access token. Set automatically from MercadoPagoConfig or requestOptions.
​
clientId
String
Your application ID (client_id).
​
refreshToken
String
The refresh token to exchange for a new access token.

​
Using seller access tokens for subsequent API calls

Once you have the seller’s access_token, pass it to any client method via MPRequestOptions to execute that request in the context of the seller’s account: 
MPRequestOptions sellerOptions = MPRequestOptions.builder()
    .accessToken(sellerAccessToken)
    .build();

// This payment is created on behalf of the seller
PaymentClient paymentClient = new PaymentClient();
Payment payment = paymentClient.create(paymentRequest, sellerOptions);

​
Code Example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.oauth.OauthClient;
import com.mercadopago.core.MPRequestOptions;
import com.mercadopago.resources.oauth.CreateOauthCredential;
import com.mercadopago.resources.oauth.RefreshOauthCredential;

// Set your marketplace access token
MercadoPagoConfig.setAccessToken("YOUR_MARKETPLACE_ACCESS_TOKEN");

OauthClient client = new OauthClient();

String appId       = "YOUR_APP_ID";
String redirectUri = "https://your-marketplace.com/oauth/callback";

// Step 1: Generate the seller authorization URL and redirect the seller to it
String authUrl = client.getAuthorizationURL(appId, redirectUri);
System.out.println("Redirect the seller to: " + authUrl);

// Step 2: After the seller authorizes, exchange the code for credentials
//         (the 'code' comes in as a query parameter on your redirect URI)
String authorizationCode = "TG-XXXXXXXX-XXXXXXXXX"; // from redirect
CreateOauthCredential credential = client.createCredential(authorizationCode, redirectUri);

String sellerAccessToken = credential.getAccessToken();
String sellerRefreshToken = credential.getRefreshToken();
System.out.println("Seller access token: " + sellerAccessToken);
System.out.println("Expires in (seconds): " + credential.getExpiresIn());

// Step 3: Store sellerAccessToken and sellerRefreshToken securely
//         Use sellerAccessToken in MPRequestOptions for seller-context API calls

// Step 4: When the access token is about to expire, refresh it
RefreshOauthCredential refreshed = client.refreshCredential(sellerRefreshToken);
String newSellerAccessToken  = refreshed.getAccessToken();
String newSellerRefreshToken = refreshed.getRefreshToken();
System.out.println("New access token: " + newSellerAccessToken);

// Step 5: Use per-request options to make API calls on behalf of the seller
MPRequestOptions sellerOptions = MPRequestOptions.builder()
    .accessToken(newSellerAccessToken)
    .build();

// Example: fetch the seller's own user info
com.mercadopago.client.user.UserClient userClient =
    new com.mercadopago.client.user.UserClient();
com.mercadopago.resources.user.User sellerInfo = userClient.get(sellerOptions);
System.out.println("Seller ID: " + sellerInfo.getId());

Build docs developers (and LLMs) love

Get started for freeTalk to us