authentication

Authentication

Payper uses OAuth 2.0 to authenticate with the PayPal REST APIs. The library automatically obtains access tokens using your PayPal credentials and manages token caching and automatic refresh for you.

---

🔑 Getting Your Credentials

Before you can authenticate, you need to obtain your API credentials from PayPal:

1. Log in to the PayPal Developer Dashboard
2. Navigate to Apps & Credentials
3. Choose Sandbox for testing or Live for production
4. Create or select an app to get your:
   • Client ID
   • Client Secret

⚠️ Important: Keep your Client Secret confidential. Never commit it to source control or expose it in client-side code.

---

🎯 Authentication Methods

Payper offers multiple ways to provide your credentials, depending on your deployment environment and security requirements.

Method 1: Environment Variables (Recommended)

Environment variables are the recommended approach for production deployments, containerized applications, and CI/CD pipelines.

For Sandbox:

export PAYPAL-CLIENT-ID="YOUR_SANDBOX_CLIENT_ID"
export PAYPAL-CLIENT-SECRET="YOUR_SANDBOX_CLIENT_SECRET"
export PAYPAL-BASE-URL="https://api-m.sandbox.paypal.com"

For Production:

export PAYPAL-CLIENT-ID="YOUR_LIVE_CLIENT_ID"
export PAYPAL-CLIENT-SECRET="YOUR_LIVE_CLIENT_SECRET"
export PAYPAL-BASE-URL="https://api-m.paypal.com"

Usage in code:

// Payper automatically reads from environment variables
var client = CatalogProductsApiClient.create();

---

Method 2: System Properties

System properties are useful for local development and testing. You can set them programmatically or via command line.

Programmatically:

// Set credentials at runtime
System.setProperty("PAYPAL-CLIENT-ID", "YOUR_CLIENT_ID");
System.setProperty("PAYPAL-CLIENT-SECRET", "YOUR_CLIENT_SECRET");
System.setProperty("PAYPAL-BASE-URL", "https://api-m.sandbox.paypal.com");

// Create the client
var client = CatalogProductsApiClient.create();

Via Command Line:

java -DPAYPAL-CLIENT-ID=YOUR_CLIENT_ID \
     -DPAYPAL-CLIENT-SECRET=YOUR_CLIENT_SECRET \
     -DPAYPAL-BASE-URL=https://api-m.sandbox.paypal.com \
     -jar your-application.jar

---

Method 3: Properties File

For local development, you can use a properties file stored outside your project directory.

1. Create a credentials file:

Create ~/.payper/credentials.properties:

PAYPAL-CLIENT-ID=YOUR_CLIENT_ID
PAYPAL-CLIENT-SECRET=YOUR_CLIENT_SECRET

2. Load and use in your code:

import io.github.eealba.payper.core.PayperConfig;
import io.github.eealba.payper.core.security.PayperAuthenticator;
import java.nio.file.Paths;
import java.io.IOException;

public class PayperSetup {
    public static void main(String[] args) throws IOException {
        // Path to credentials file
        var credentialPath = Paths.get(
            System.getProperty("user.home"), 
            ".payper", 
            "credentials.properties"
        );
        
        // Create authenticator for sandbox
        var authenticator = PayperAuthenticator.PayperAuthenticators
            .ofSandBox(credentialPath);
        
        // Build configuration
        var payperConfig = PayperConfig.builder()
            .authenticator(authenticator)
            .build();
        
        // Create client with custom config
        var ordersApi = CheckoutOrdersApiClient.create(payperConfig).orders();
    }
}

---

Method 4: Programmatic Suppliers (Advanced)

For advanced scenarios where credentials need to be retrieved dynamically (e.g., from a secret manager or vault), you can use suppliers.

Example:

import io.github.eealba.payper.core.PayperConfig;
import io.github.eealba.payper.core.security.PayperAuthenticator;

public class DynamicCredentials {
    public static void main(String[] args) {
        // Suppliers that fetch credentials dynamically
        var authenticator = PayperAuthenticator.PayperAuthenticators.ofSandBox(
            () -> fetchClientIdFromVault(),      // Supplier<char[]>
            () -> fetchClientSecretFromVault()   // Supplier<char[]>
        );
        
        var config = PayperConfig.builder()
            .authenticator(authenticator)
            .build();
        
        var client = SubscriptionsApiClient.create(config);
    }
    
    private static char[] fetchClientIdFromVault() {
        // Implement your secret retrieval logic
        return "CLIENT_ID".toCharArray();
    }
    
    private static char[] fetchClientSecretFromVault() {
        // Implement your secret retrieval logic
        return "CLIENT_SECRET".toCharArray();
    }
}

---

🌍 Environment Configuration

Sandbox vs Live

Payper supports both PayPal's Sandbox (testing) and Live (production) environments.

Environment	Base URL
Sandbox	https://api-m.sandbox.paypal.com
Live	https://api-m.paypal.com

Sandbox Configuration:

var authenticator = PayperAuthenticator.PayperAuthenticators.ofSandBox(
    () -> clientId,
    () -> clientSecret
);

Live Configuration:

var authenticator = PayperAuthenticator.PayperAuthenticators.ofLive(
    () -> clientId,
    () -> clientSecret
);

---

🔐 Best Practices

✅ Do's

1. Use Environment Variables in Production - Store credentials in your deployment environment
2. Use Secret Management Systems - AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, etc.
3. Rotate Credentials Regularly - Update your API credentials periodically
4. Use Sandbox for Testing - Always test with sandbox credentials first
5. Validate Credentials - Test your setup before deploying to production

❌ Don'ts

1. Never Commit Credentials to Git - Add credentials files to .gitignore
2. Never Hardcode Credentials - Avoid embedding secrets in source code
3. Never Share Credentials - Each application should have its own API credentials
4. Never Use Production Credentials in Development - Keep sandbox and live credentials separate
5. Never Log Credentials - Ensure sensitive data isn't written to logs

---

🔄 Token Management

Payper handles all token lifecycle management automatically:

• Automatic Token Acquisition - Fetches OAuth 2.0 access tokens on first use
• Token Caching - Reuses tokens for subsequent requests
• Automatic Refresh - Renews expired tokens transparently
• Thread-Safe - Token management is safe for concurrent use

You don't need to write any code for token management - it's all handled behind the scenes.

---

🧪 Testing Your Authentication

Here's a simple test to verify your authentication is working:

import io.github.eealba.payper.catalog.products.v1.api.CatalogProductsApiClient;

public class AuthTest {
    public static void main(String[] args) {
        try {
            // This will use your configured credentials
            var client = CatalogProductsApiClient.create();
            
            // Try to list products (requires authentication)
            var response = client.products()
                .list()
                .withPageSize(1)
                .retrieve()
                .toResponse();
            
            if (response.statusCode() == 200) {
                System.out.println("✅ Authentication successful!");
            } else {
                System.out.println("❌ Authentication failed: " + response.statusCode());
            }
        } catch (Exception e) {
            System.out.println("❌ Error: " + e.getMessage());
        }
    }
}

---

🆘 Troubleshooting

Authentication Failed (401)

Possible causes:

• Invalid Client ID or Client Secret
• Credentials from wrong environment (sandbox vs live)
• Credentials expired or revoked

Solutions:

• Verify credentials in PayPal Developer Dashboard
• Ensure you're using the correct base URL for your environment
• Generate new credentials if needed

Connection Errors

Possible causes:

• Network connectivity issues
• Firewall blocking outbound HTTPS
• Incorrect base URL

Solutions:

• Check your internet connection
• Verify firewall settings allow HTTPS to PayPal
• Confirm the base URL is correct for your environment

---

📚 Next Steps

• Configuration - Learn about advanced configuration options
• Use Cases - See authentication in action with complete examples
• PayPal OAuth 2.0 Documentation - Official PayPal authentication guide

---

🔗 Additional Resources

• PayPal Developer Dashboard
• PayPal API Credentials Guide
• OAuth 2.0 Standard