Skip to content
Nappai Documentation

PayPal Payout Item

This component allows you to manage specific items within a PayPal Payout Batch. It acts as a tool to either check the status of a payment or cancel a transaction that has already been sent out. Think of it as a way to inspect or stop a single check from a large envelope of payments you sent to many people at once.

How it Works

This component connects directly to the PayPal Payouts API. When you use it, Nappai automatically handles the secure connection to PayPal using the credentials you have set up.

Depending on what you choose in the Operation field, the component will do one of two things:

  1. Retrieve Details: It looks up the current status (e.g., pending, succeeded, failed) of a specific payment item using its unique ID.
  2. Cancel: It attempts to stop the processing of a specific payment item before it is completed.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type PayPal API and fill in the required fields (Client ID, Client Secret, and Environment).
  3. In your workflow, select the saved credential in the Credential input field of this node.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • cancel: Use this to stop the processing of a specific payment item within a batch. This is useful if a payment was sent in error or needs to be reversed before completion.
  • get: Use this to retrieve detailed information about a specific payment item, such as its current status, sender transaction ID, and payment date.

To use the component, first select the operation you need in the “Operation” field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Credential: Select the PayPal API credential you created earlier to authenticate your connection.

    • Visible in: All operations

  • Operation: Select whether you want to cancel a payment item or retrieve its details. This determines how the component behaves.

    • Visible in: All operations

  • Payout Item ID: The unique identifier for the specific payment item you want to check or cancel. You usually find this ID after creating the initial payout batch.

    • Visible in: cancel, get

Outputs

After the component runs, it provides the following outputs which you can use in subsequent steps of your workflow:

  • response: Contains the full data returned by PayPal. For a get operation, this includes details like status and date. For a cancel operation, it confirms if the cancellation was successful.
  • status_code: A numerical code indicating if the request was successful (e.g., 200 for success, 204 for no content) or if there was an error (e.g., 400 for bad request, 404 for not found).
  • error_message: If something goes wrong, this will contain a clear text explanation of the error. If the operation is successful, this will likely be empty.
  • response_headers: Technical details about the request, mostly useful for developers debugging connection issues.

Output Data Example (JSON)

Here is an example of what the response output might look like when you use the get operation successfully: json { “payout_item_id”: “7B89K7L5M3”, “sender_batch_id”: “batch_001”, “payout_item”: { “recipient_type”: “EMAIL”, “amount”: { “value”: “10.00”, “currency”: “USD” }, “note”: “Payment for services”, “receiver”: “user@example.com”, “sender_item_id”: “item_123” }, “links”: [ { “href”: “https://api.sandbox.paypal.com/v1/payments/payouts/batch_001/items/7B89K7L5M3”, “rel”: “self”, “method”: “GET” } ] }

Connectivity

This component is typically used after a PayPal Payout Batch component.

  1. First, you create a batch payout using a different component.
  2. That initial component will generate a list of items with unique IDs.
  3. You connect the Payout Item ID from that previous step into this component’s Payout Item ID input.
  4. You then decide if you want to just check the status (get) or try to stop it (cancel).

Usage Example

Imagine you have sent a batch of 50 payments to freelancers. One freelancer reports they shouldn’t have been paid.

  1. You find that freelancer’s Payout Item ID in your records.
  2. Add this component to your workflow.
  3. Set Operation to cancel.
  4. Enter the Payout Item ID into the input field.
  5. Run the workflow. The system will attempt to stop that specific payment. If it is still pending, it will be cancelled. If it has already been paid, the system will return an error message telling you it was too late.

Tips and Best Practices

  • Check IDs First: Always ensure you have the correct Payout Item ID before canceling. Canceling the wrong item can lead to difficult recovery situations.
  • Use ‘get’ to Verify: Before attempting to cancel, you might want to run a get operation first to see the current status. If the status is already “Succeeded,” cancellation will fail.
  • Sandbox Testing: Always test your cancellation logic using the sandbox environment (set in your Credential) before applying changes to real money transactions.

Security Considerations

  • Credential Safety: Ensure your PayPal API Credential (Client ID and Client Secret) is kept private. Never share these secrets publicly or commit them to version control.
  • Authorization: This component requires valid OAuth2 permissions. Ensure your PayPal account has the necessary permissions to manage payouts and cancel items.