Payouts SDK

You can use the PayPal Payouts SDK for Java or Python 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 the Payouts API with less code.
• Manage API responses and handle errors.

If you want a more customized integration or use a language not supported by the SDK, use the Payouts API directly. For more information, see Use Payouts API.

Install SDK

Install the Payouts SDK in your preferred 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.1.1</version>
</dependency>

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;

public class PayPalClient 
{
    /**
     * Set up PayPal SDK environment with your access credentials. 
     * This sample uses SandboxEnvironment. In production, use LiveEnvironment.
     */
    private PayPalEnvironment environment = new PayPalEnvironment.Sandbox(
        System.getProperty("PAYPAL_CLIENT_ID") != null ? System.getProperty("PAYPAL_CLIENT_ID") : "PAYPAL_CLIENT_ID", 
        System.getProperty("PAYPAL_CLIENT_SECRET") != null ? System.getProperty("PAYPAL_CLIENT_SECRET") : "PAYPAL_CLIENT_SECRET");
    /**
     * Returns a PayPal HTTP client instance.
     * Use this instance to call PayPal APIs.
     */
    PayPalHttpClient client = new PayPalHttpClient(environment);
    /**
     * Method to get client object
     * @return PayPalHttpClient client
     */ 
    public PayPalHttpClient client() 
    {
        return this.client;
    }
}

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

Create payout batch

Use the following code samples to create a payout batch.

Java

package com.paypal;

import com.paypal.http.Encoder;
import com.paypal.http.HttpResponse;
import com.paypal.http.exceptions.HttpException;
import com.paypal.http.serializer.Json;
import com.paypal.payouts.Error;
import com.paypal.payouts.*;
import org.apache.commons.lang3.RandomStringUtils;
import org.json.JSONObject;

import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.IntStream;

public class CreatePayoutsBatch extends PayPalClient {
    private static final Encoder encoder = new Encoder();
    /**
     * This sample creates a payout batch with five payout items.
     * Calls the create batch payout API (POST - /v1/payments/payouts).
     * A maximum of 15000 payout items are supported in a single batch request.
     * @return - Response for the create batch payout call.
     * @throws IOException - Throws exception if the API call fails.
     */
    public HttpResponse<CreatePayoutResponse> createPayout() throws IOException {
        PayoutsPostRequest request = buildRequestBody(false);
        HttpResponse<CreatePayoutResponse> response = client().execute(request);
        System.out.println("Response Body:");
        System.out.println(new JSONObject(new Json().serialize(response.result())).toString(4));
        return response;
    }
    /**
     * Builds a request body to create payout batch with five payout items to receivers' email.
     * @param isValidationFailure - Includes validation failure in payload.
     * @return - Request payload for Payouts create (POST) request.
     */
    private PayoutsPostRequest buildRequestBody(boolean isValidationFailure) {
        List<PayoutItem> items = IntStream
                .range(1, 6)
                .mapToObj(index -> new PayoutItem()
                        .senderItemId("Test_txn_" + index)
                        .note("Thank you for your business!")
                        .receiver("payout-sdk-" + index + "@paypal.com")
                        .amount(new Currency()
                                .currency("USD")
                                .value(isValidationFailure ? "1.0.0" : "1.00")))
                .collect(Collectors.toList());
        CreatePayoutRequest payoutBatch = new CreatePayoutRequest()
                .senderBatchHeader(new SenderBatchHeader()
                        .senderBatchId("Test_sdk_" + RandomStringUtils.randomAlphanumeric(7))
                        .emailMessage("SDK payouts test txn")
                        .emailSubject("This is a test transaction from SDK")
                        .recipientType("EMAIL"))
                .items(items);
        return new PayoutsPostRequest()
                .requestBody(payoutBatch);
    }
    /**
     * Driver method to execute this sample.
     * This creates a payout batch with five items and prints the response.
     * @param args
     * @throws IOException - Throws exception if the API call fails.
     */
    public static void main(String[] args) throws IOException {
        new CreatePayoutsBatch().createPayout();
    }
}

Track status

Use the payout batch ID to retrieve the payout batch details.

Java

package com.paypal;

import com.paypal.http.Encoder;
import com.paypal.http.HttpResponse;
import com.paypal.http.exceptions.HttpException;
import com.paypal.http.serializer.Json;
import com.paypal.payouts.CreatePayoutResponse;
import com.paypal.payouts.Error;
import com.paypal.payouts.PayoutBatch;
import com.paypal.payouts.PayoutsGetRequest;
import org.json.JSONObject;

import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class GetPayoutBatch extends PayPalClient {
    private static final Encoder encoder = new Encoder();
    /**
     * Uses the show payout batch details API (GET - /v1/payments/payouts/<batchId>) to retrieve the payout batch details. 
     * This paginated API supports retrieving a maximum of 1000 items per page. 
     * Check 'links' in the response for previous and next page of URIs.
     * Add 'totalRequired' parameter to know the total number of pages available.
     *
     * @param batchId - Id of a Payouts batch.
     * @return - Returns the details of the payout batch.
     * @throws IOException - Throws exception if the API call fails.
     */
    public HttpResponse<PayoutBatch> getPayoutBatch(String batchId) throws IOException {
        PayoutsGetRequest request = new PayoutsGetRequest(batchId)
                //Optional parameters, maximum of 1000 items are retrieved by default.
                .page(1)
                .pageSize(10)
                .totalRequired(true);
        try {
            HttpResponse<PayoutBatch> response = client().execute(request);
            System.out.println("Response Body:");
            System.out.println(new JSONObject(new Json().serialize(response.result())).toString(4));
            return response;
        } catch (IOException e) {
            //Client side failure
            System.out.println(e);
            throw e;
        }
    }
    /**
     * Driver method to execute this sample and retrieve the payout batch details.
     * To retrieve a valid Payouts batch it creates a Payouts Batch with 5 items and use that id for retrieval
     *
     * @param args
     * @throws IOException when call to the api fails
     */
    public static void main(String[] args) throws IOException {
        HttpResponse<CreatePayoutResponse> response = new CreatePayoutsBatch().createPayout();
        new GetPayoutBatch().getPayoutBatch(response.result().batchHeader().payoutBatchId());
    }
}

SDK reference

• Payouts Java SDK
• Payouts Python SDK