Skip to content
Nappai Documentation

PayPal Invoice

PayPal Invoice is a powerful tool within Nappai that connects your automation workflows directly to your PayPal account. It allows you to manage the entire lifecycle of digital invoices without leaving your dashboard. Whether you need to create a new invoice for a service, send it to a client, check its status, or record that it has been paid, this component handles the connection to PayPal’s servers securely and efficiently.

How it Works

This component acts as a secure bridge between Nappai and PayPal’s invoicing API. When you configure the component with your PayPal credentials, it authenticates your request to ensure that only authorized actions are performed on your account.

Depending on the action you choose (such as creating or sending an invoice), the component sends specific data—like item names, quantities, amounts, and recipient emails—to PayPal. PayPal then processes this information and returns a response, such as a unique Invoice ID or confirmation that the invoice was sent successfully. You can then use this information in subsequent steps of your automation, such as updating your internal records or sending a notification.

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 and Client Secret). You will also need to select your environment (Sandbox for testing or Live for real transactions).
  3. In your workflow, select the saved credential in the Credential input field of this node.

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:

  • Operation: Choose the specific action you want to perform on the invoice. Common actions include creating, sending, retrieving, canceling, or marking an invoice as paid.

    • Visible in: All Operations

  • Get Mode: Defines how you want to retrieve invoice data. You can choose to retrieve a single invoice by its ID or list all invoices based on filters.

    • Visible in: All Operations

  • Invoice ID: The unique identifier for an existing PayPal invoice. This is required for actions like canceling, retrieving details, sending, or marking an invoice as paid.

    • Visible in: All Operations

  • Recipient Email: The email address of the person or business you are sending the invoice to.

    • Visible in: All Operations

  • Currency: The currency in which the invoice will be issued (e.g., USD, EUR).

    • Visible in: All Operations

  • Item Name: The name of the product or service being invoiced.

    • Visible in: All Operations

  • Quantity: The number of units for the item being invoiced. The default value is 1.

    • Visible in: All Operations

  • Unit Amount: The price per unit for the item. Enter this as a decimal string (e.g., “25.00”).

    • Visible in: All Operations

  • Due Date: The date by which the payment is due. Use the format YYYY-MM-DD (e.g., 2023-12-31).

    • Visible in: All Operations

  • Note: Any additional notes or messages you want to include for the recipient.

    • Visible in: All Operations

  • Terms and Conditions: The terms and conditions text that will appear on the invoice.

    • Visible in: All Operations

  • Payment Method: The method used for payment (e.g., Credit Card, Bank Transfer). This is only relevant when marking an invoice as paid.

    • Visible in: All Operations

  • Payment Date: The date the payment was received. Use the format YYYY-MM-DD. This is required when marking an invoice as paid.

    • Visible in: All Operations

  • Limit: The maximum number of invoices to return in a list. The value must be between 1 and 100.

    • Visible in: All Operations

Outputs

When the component successfully executes an operation, it provides data that you can use in subsequent steps of your workflow.

Output Data Example (JSON)

json { “invoice_id”: “INV2-XXXX-XXXX-XXXX”, “status”: “SENT”, “link”: “https://www.paypal.com/invoice/p/#/INV2-XXXX-XXXX-XXXX/pay”, “details”: { “currency”: “USD”, “items”: [ { “name”: “Web Design Service”, “quantity”: 1, “unit_amount”: “500.00” } ], “total_amount”: { “currency”: “USD”, “value”: “500.00” }, “due_date”: “2023-12-31”, “note”: “Thank you for your business.” }, “error_message”: null }

Connectivity

This component is typically used at the start of an invoicing workflow or after receiving a new order.

  • Upstream: It often receives data from Data Retrieval components (like fetching customer details from a CRM) or Form inputs (where users manually enter order details). The outputs from these components can be mapped to fields like Recipient Email, Item Name, and Unit Amount.
  • Downstream: After creating or retrieving an invoice, the output (specifically invoice_id or link) is often connected to Email components to send notifications, or Database components to update your internal records. If you are marking an invoice as paid, the output can trigger Notification components to alert your team.

Usage Example

Scenario: Automatically Sending a New Invoice

  1. Create Invoice: Use the component with Operation set to Create. Map the Recipient Email, Item Name, Unit Amount, and Currency from your CRM data.
  2. Get Result: The component returns the invoice_id and status (e.g., “DRAFT”).
  3. Send Invoice: Add a second instance of the PayPal Invoice component. Set Operation to Send. Map the Invoice ID from the previous step into the Invoice ID field.
  4. Notify Team: Connect the output to an Email or Slack notification to inform your sales team that the invoice has been sent.

Important Notes

⚠️ Development Status This component is currently in a development phase (is_development = True). While it is functional, please be aware that the API or behavior may change as the component is refined. It is recommended to test thoroughly in a sandbox environment before relying on it for critical production tasks.

🔒 Security & Credentials Ensure that your PayPal API credentials (Client ID and Client Secret) are kept secure. Never share these credentials publicly. The component is designed to handle these securely when configured via the Nappai Credentials panel.

💡 Environment Selection Be careful when selecting your Environment. The Sandbox environment is for testing only and does not involve real money. The Live environment processes real transactions. Always verify which environment is active when performing financial operations.

📋 Required Fields for Specific Actions Some operations require specific inputs. For example, you cannot cancel or mark an invoice as paid without providing the Invoice ID. Similarly, creating an invoice requires item details (Name, Quantity, Unit Amount). Make sure to fill in all required fields for the selected operation to avoid errors.

Tips and Best Practices

  • Use Sandbox First: Always test your workflows using the Sandbox environment before switching to Live to avoid accidental real-world transactions.
  • Map Dynamic Data: Use Mapping Mode to dynamically pull customer emails and item details from other components instead of typing them manually. This makes your workflows more reusable and accurate.
  • Handle Errors: Check the error_message output in your workflow. If an invoice fails to send (e.g., invalid email), you can add logic to notify you or retry the action.
  • Keep Track of IDs: The invoice_id returned by the component is crucial for future actions like retrieving details or marking as paid. Ensure you map this ID to subsequent steps if you plan to manage the invoice further.
  • Date Format: When entering dates, always use the YYYY-MM-DD format to ensure PayPal accepts the input correctly.

Security Considerations

This component interacts with PayPal’s API using secure authentication. Ensure that you only use legitimate PayPal API credentials. The Client Secret is sensitive information and should never be hardcoded or exposed in shared workflows. Always use the Credentials section in Nappai to manage this securely.