Payouts SDK and APIs reference

The Payouts SDK is a set of libraries that help you add PayPal Payouts to your server application. It works with Node.js, Java, .NET, and Python. You cannot use it in browsers or on the client side.

With the SDK, you can:

• Call Payouts APIs quickly.
• Manage authentication automatically.
• Handle API responses easily.

If you use the Payouts API directly, you must write code for HTTP requests, authentication, and error handling. The SDK simplifies this work. It follows best practices and keeps up with API changes. You write less code and get clear examples for each language.

Note: The SDK is updated regularly to support new API features. For advanced or highly customized needs, you may want to use the API directly for greater flexibility.

Get started

To get started:

1. Install the SDK for your language.
2. Configure your PayPal credentials.
3. Send and manage payouts.

Install the SDK

Install the Payouts SDK for your language:

PHP

composer require paypal/payouts-sdk

Node.js

npm install @paypal/payouts-sdk

Java

<dependency>
  <groupId>com.paypal.sdk</groupId>
  <artifactId>payouts-sdk</artifactId>
  <version>1.0.2</version>
</dependency>

Python

pip install paypal-payouts-sdk

.NET

dotnet add package PayPalCheckoutSdk.Payouts

Configure your PayPal credentials

Set up your PayPal client ID and secret for authentication:

PHP

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

$clientId = "CLIENT_ID";
$clientSecret = "CLIENT_SECRET";
$environment = new SandboxEnvironment($clientId, $clientSecret);
$client = new PayPalHttpClient($environment);

Node.js

const paypal = require('@paypal/payouts-sdk');
const environment = new paypal.core.SandboxEnvironment('CLIENT_ID', 'CLIENT_SECRET');
const client = new paypal.core.PayPalHttpClient(environment);

Java

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

Python

from paypalcheckoutsdk.core import PayPalHttpClient, SandboxEnvironment

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

.NET

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

Send and manage payouts

Send a payout

Use the SDK to create a payout batch:

PHP

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"
        ]
    ]
];

$response = $client->execute($request);

Node.js

const request = new paypal.payouts.PayoutsPostRequest();
request.requestBody({
  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"
    }
  ]
});

client.execute(request)
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error(err);
  });

Java

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");
  }}));
}});

client.execute(request);

Python

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"
        }
    ]
})

client.execute(request)

.NET

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"
        }
    }
});

await client.Execute(request);

Check payout status

To check the status of a payout batch, use the batch ID returned when you created the payout:

PHP

use PayPal\Payouts\PayoutsGetRequest;

$request = new PayoutsGetRequest("batch_001");
$response = $client->execute($request);
$status = $response->result->batch_header->batch_status;
echo $status;

Node.js

const request = new paypal.payouts.PayoutsGetRequest("batch_001");
client.execute(request)
  .then((response) => {
    console.log(response.result.batch_header.batch_status);
  })
  .catch((err) => {
    console.error(err);
  });

Java

PayoutsGetRequest request = new PayoutsGetRequest("batch_001");
HttpResponse<PayoutBatch> response = client.execute(request);
String status = response.result().batchHeader().batchStatus();
System.out.println(status);

Python

from paypalcheckoutsdk.payouts import PayoutsGetRequest

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

.NET

var request = new PayoutsGetRequest("batch_001");
var response = await client.Execute(request);
var status = response.Result<Dictionary<string, object>>()["batch_header"]; // Adjust as needed for your SDK version
Console.WriteLine(status);

Error handling

The SDK throws exceptions for errors such as invalid requests or authentication failures. Catch and inspect the exception to handle errors appropriately:

PHP

try {
    $response = $client->execute($request);
} catch (HttpException $ex) {
    echo $ex->statusCode;
    echo $ex->getMessage();
}

Node.js

client.execute(request)
  .then((response) => {
    // handle success
  })
  .catch((err) => {
    console.error(err.statusCode);
    console.error(err.message);
  });

Java

try {
    HttpResponse<PayoutBatch> response = client.execute(request);
} catch (HttpException ex) {
    System.out.println(ex.statusCode());
    System.out.println(ex.getMessage());
}

Python

try:
    response = client.execute(request)
except IOError as ex:
    print(ex.status_code)
    print(ex.message)

.NET

try
{
    var response = await client.Execute(request);
}
catch (HttpException ex)
{
    Console.WriteLine(ex.StatusCode);
    Console.WriteLine(ex.Message);
}