Payouts SDK and APIs reference

You have two options to integrate PayPal Payouts to your app:

• Use the Payouts SDK if you want a streamlined integration with built-in authentication, error handling, and support for Java, PHP, Python, or .NET.
• Use the Payouts APIs directly if:
  • You want more control over the API calls.
  • You need to customize your integration.
  • You use a language not supported by the SDK.

Both options use the PayPal Payouts REST APIs.

Use Payouts SDK

You can use the PayPal Payouts SDK for Java, PHP, Python, or .NET to work with the Payouts REST API. The SDK helps keep your integration up to date with API changes and is intended for server-side use only.

With the SDK, you can:

• Handle OAuth 2.0 authentication automatically.
• Call Payouts APIs with less code.
• Manage API responses and errors.

Install SDK

Install the Payouts SDK for your language:

Java

// Create a Java Maven or Gradle project in your directory, then add the following dependency to the project from Maven Central.
<dependency>
  <groupId>com.paypal.sdk</groupId>
  <artifactId>payouts-sdk</artifactId>
  <version>1.0.2</version>
</dependency>

PHP

# Create a PHP project in your directory, then run the following command to install the PayPal Payouts PHP SDK.
composer require paypal/paypal-payouts-sdk ~1.0.0

Python

# Create a Python project in your directory, then run the following command to install the PayPal Payouts Python SDK.
pip install paypal-payouts-sdk

.NET

# Create a DotNet project in your directory, then run the following command to install the PayPal Payouts DotNet SDK.
dotnet add package PayPalCheckoutSdk.Payouts

Set up your environment and credentials

1. Create a new file in your preferred language in the directory where you installed the SDK.
2. Copy the following code sample for your language to initialize the SDK and configure your environment.
3. Update the code with your PayPal client ID and secret.
4. Set the environment to SandboxEnvironment for testing or LiveEnvironment for production.

Java

import com.paypal.core.PayPalEnvironment;
import com.paypal.core.PayPalHttpClient;

PayPalEnvironment environment = new PayPalEnvironment.Sandbox(
    "CLIENT_ID",
    "CLIENT_SECRET"
);
PayPalHttpClient client = new PayPalHttpClient(environment);

PHP

use PayPal\Core\PayPalHttpClient;
use PayPal\Core\SandboxEnvironment;

class PayPalClient {
    /**
     * Returns a PayPal HTTP client instance with the environment that has access
     * credentials. Use this instance to call PayPal APIs, provided the
     * credentials have access.
     */
    public static function client() {
        return new PayPalHttpClient(self::environment());
    }
    /**
     * Set up and return PayPal PHP SDK environment with PayPal access credentials.
     * This sample uses SandboxEnvironment. In production, use LiveEnvironment.
     */
    public static function environment() {
        $clientId = getenv("CLIENT_ID") ?: "PAYPAL-CLIENT-ID";
        $clientSecret = getenv("CLIENT_SECRET") ?: "PAYPAL-CLIENT-SECRET";
        return new SandboxEnvironment($clientId, $clientSecret);
    }
}

Python

from paypalcheckoutsdk.core import PayPalHttpClient, SandboxEnvironment

environment = SandboxEnvironment(client_id="CLIENT_ID", client_secret="CLIENT_SECRET")
client = PayPalHttpClient(environment)

.NET

using PayPalCheckoutSdk.Core;

var environment = new SandboxEnvironment("CLIENT_ID", "CLIENT_SECRET");
var client = new PayPalHttpClient(environment);

Note: For more information on finding your REST API credentials for both sandbox and live environments, see Sandbox accounts.

Send and manage payouts

Use the SDK to create and manage payout batches.

Java

// Create a new payout request and set the batch and item details
PayoutsPostRequest request = new PayoutsPostRequest();
request.requestBody(new HashMap<String, Object>() {{
  put("sender_batch_header", new HashMap<String, Object>() {{
    put("sender_batch_id", "batch_001");
    put("email_subject", "You have a payout!");
  }});
  put("items", Arrays.asList(new HashMap<String, Object>() {{
    put("recipient_type", "EMAIL");
    put("amount", new HashMap<String, Object>() {{
      put("value", "10.00");
      put("currency", "USD");
    }});
    put("receiver", "recipient@example.com");
    put("note", "Thanks for your service!");
    put("sender_item_id", "item_001");
  }}));
}});

// Send the payout request
client.execute(request);

PHP

// Create a new payout request and set the batch and item details
use PayPal\Payouts\PayoutsPostRequest;

$request = new PayoutsPostRequest();
$request->body = [
    "sender_batch_header" => [
        "sender_batch_id" => "batch_001",
        "email_subject" => "You have a payout!"
    ],
    "items" => [
        [
            "recipient_type" => "EMAIL",
            "amount" => [
                "value" => "10.00",
                "currency" => "USD"
            ],
            "receiver" => "recipient@example.com",
            "note" => "Thanks for your service!",
            "sender_item_id" => "item_001"
        ]
    ]
];

// Send the payout request
$response = $client->execute($request);

Python

# Create a new payout request and set the batch and item details
from paypalcheckoutsdk.payouts import PayoutsPostRequest

request = PayoutsPostRequest()
request.request_body({
    "sender_batch_header": {
        "sender_batch_id": "batch_001",
        "email_subject": "You have a payout!"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": "10.00",
                "currency": "USD"
            },
            "receiver": "recipient@example.com",
             "note": "Thanks for your service!",
            "sender_item_id": "item_001"
        }
    ]
})

# Send the payout request
response = client.execute(request)

.NET

// Create a new payout request and set the batch and item details
var request = new PayoutsPostRequest();
request.RequestBody = new {
    sender_batch_header = new {
        sender_batch_id = "batch_001",
        email_subject = "You have a payout!"
    },
    items = new[] {
        new {
            recipient_type = "EMAIL",
            amount = new {
                value = "10.00",
                currency = "USD"
            },
            receiver = "recipient@example.com",
            note = "Thanks for your service!",
            sender_item_id = "item_001"
        }
    }
};

// Send the payout request
var response = await client.Execute(request);

Check payout status

To check the status of a payout, use the payout batch ID.

Java

// Create a request to get the payout batch status
PayoutsGetRequest request = new PayoutsGetRequest("batch_001");
HttpResponse<PayoutBatch> response = client.execute(request);
String status = response.result().batchHeader().batchStatus();
System.out.println(status);

PHP

// Create a request to get the payout batch status
use PayPal\Payouts\PayoutsGetRequest;

$request = new PayoutsGetRequest("batch_001");

// Execute the request and get the status
$response = $client->execute($request);
$status = $response->result->batch_header->batch_status;
echo $status;

Python

# Create a request to get the payout batch status
from paypalcheckoutsdk.payouts import PayoutsGetRequest

request = PayoutsGetRequest("batch_001")
response = client.execute(request)
status = response.result["batch_header"]["batch_status"]
print(status)

.NET

// Create a request to get the payout batch status
var request = new PayoutsGetRequest("batch_001");
var response = await client.Execute(request);

Use Payouts APIs

You can also use the Payouts APIs directly. This method gives you control over HTTP requests, authentication, and error handling. Use this approach if you need advanced or custom integration.

The following APIs are available for Payouts integration:

• Generate access token: POST /v1/oauth2/token
• Create payout batch: POST /v1/payments/payouts
• Track status: GET /v1/payments/payouts/{id}

For more information and detailed steps, see Use Payouts APIs.

SDK reference

• Payouts Java SDK
• Payouts PHP SDK
• Payouts Python SDK
• Payouts .NET SDK