PayPal

1. Overview

Paypal is a leading global online payment solution that allows users and merchants to make and receive electronic payments securely and conveniently. Its Payouts API is specifically designed to help businesses send mass payments to multiple recipients.

With GoInsight's Paypal node, you can seamlessly integrate the batch payment functionality into your automated workflows. This makes processing commission payments, rebates, rewards, or any scenario requiring payments to multiple people efficient and automated. You can achieve full lifecycle management of payout batches and individual payout items, including:

• Create Payout Batches: Initiate a mass payment request to multiple recipients with a single API call.
• Query Payout Status: Get detailed information for an entire payout batch or a specific payout item within a batch.
• Manage Payout Items: Cancel an unprocessed payout item under specific conditions.

2. Prerequisites

• Before using this node, you need to have a valid Paypal Business Account.
• You need to create an application in your Paypal Developer account to obtain a Client ID and Secret for API calls.
• Please ensure that the Payouts feature is enabled for your account and that you have the necessary permissions to perform the relevant operations.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on two core resources in Paypal: "Payout Batches" and "Payout Items," allowing you to automate the management of your mass payment processes.

Operation Details

Create a Payout

Creates a PayPal payout batch with a specified batch header and payout items in a single request.

Input Parameters:

• SenderBatchHeader: A JSON string or dictionary representing the batch header (e.g., containing fields like sender_batch_id, email_subject).
• Items: A JSON string or list of objects representing the payout items, with each item containing information like recipient_type, amount, receiver.

Options:

• Mode: The mode for the API call, can be sandbox or live.

Output:

• PayoutBatchId (string): The ID of the created payout batch.
• BatchHeader (object): A JSON representation of the returned PayPal batch_header object.
• Links (object-array): A JSON array of link objects for the created payout batch.
• StatusCode (number): The HTTP status code or an operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message if the request fails; empty on success.

Get a Payout

Retrieves the details of a PayPal payout batch by its batch ID.

Input Parameters:

• PayoutBatchId: The ID of the payout batch to retrieve.

Options:

• Mode: The mode for the API call, can be sandbox or live.

Output:

• PayoutBatch (object): A JSON object representing the payout batch details.
• StatusCode (number): The HTTP status code or an operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message if the request fails; empty on success.

Get a Payout Item

Retrieves the details of a specific PayPal payout item by its ID.

Input Parameters:

• PayoutItemId: The ID of the payout item to retrieve.

Options:

• Mode: The mode for the API call, can be sandbox or live.

Output:

• PayoutItem (object): A JSON object containing the payout item details.
• StatusCode (number): The HTTP status code or an operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message if the request fails; empty on success.

Cancel a Payout Item

Cancels a specified PayPal payout item by its ID.

Input Parameters:

• PayoutItemId: The ID of the payout item to cancel.

Options:

• Mode: The mode for the API call, can be sandbox or live.

Output:

• Cancelled (bool): Indicates whether the payout item was successfully cancelled.
• StatusCode (number): The HTTP status code or an operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message if the cancellation fails; empty on success.

5. Example Usage

This section will guide you through creating a simple workflow to initiate a batch of PayPal payments to multiple recipients.

Workflow Overview

A basic workflow consists of three nodes: a Start node to initiate the process, a Paypal: Create a Payout node to execute the payment operation, and an Answer node to output the result.

Step-by-Step Guide

1. Add Tool Node:
   • On the workflow canvas, click the "+" sign to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • In the tool list, find and select Paypal.
   • In the list of supported operations for Paypal, click to select Create a Payout, which will add a corresponding node to the canvas.
2. Configure Node:
   • Click on the newly added Create a Payout node, and its configuration panel will expand on the right.
   • Credential Configuration: At the top of the panel, find the credential field. Click the dropdown menu and select your pre-configured Paypal credential.
   • Parameter Entry: Fill in the required parameters to create the payout batch.
   • SenderBatchHeader: This is a JSON string that defines the metadata for the entire batch. The sender_batch_id must be unique to prevent duplicate processing.
   • Items: This is a JSON string containing an array of all payout items. Each item defines the recipient, amount, and currency.
   • Mode (Optional): The default is sandbox for testing. For actual payments, ensure this is set to live.
3. Run and Validate:
   • Once all required parameters are correctly filled in, the error prompt in the top right corner of the workflow canvas will disappear.
   • Click the "Run" button in the top right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top right corner to view the detailed input and output of the node. In the output, you should see the PayoutBatchId, indicating that the batch was created successfully.

Final Workflow Display

After completing the steps above, your entire workflow is configured. Clicking "Run" will successfully create and begin processing a new payout batch in your Paypal account.

6. FAQs

Q: Why did my payout request fail with a 401/403 error?

A: This is usually related to your API credentials or account permissions. Please check the following:

• Credential Correctness: Ensure that the Client ID and Secret you configured in GoInsight are accurate and match the mode you have selected (sandbox or live).
• API Permissions: Log in to your Paypal Developer Dashboard and check if your application has been granted the Payouts permission.
• Account Status: Ensure your Paypal Business Account is in good standing and has a sufficient balance to complete the payment.

Q: How do I construct the JSON strings for the SenderBatchHeader and Items parameters?

A: Both of these parameters must strictly adhere to the JSON format.

• You can use GoInsight's code node or other text processing nodes to dynamically generate these JSON strings.
• When filling them in manually, make sure all keys and string values are enclosed in double quotes ".
• You can refer to the examples in 5. Example Usage or consult the official Paypal documentation for a list of all available fields.

Q: What is the difference between sandbox mode and live mode?

A: These are two different environments provided by the Paypal API:

• sandbox: A completely isolated testing environment. All transactions made in this mode are simulated and do not involve real money. You need to use API credentials and test accounts specifically generated for the sandbox environment. This is the recommended mode for developing and testing your workflows.
• live: The real transaction environment. All operations performed in this mode will process real funds. Be sure to thoroughly test your workflow before switching to this mode and use your production environment API credentials.

7. Official Documentation

For more information on advanced API usage and a complete list of parameters, please refer to:

Official PayPal Payouts API Documentation