PayPal Integration

Connect PayPal to Syncaut to automate payment flows, order management, refunds, and invoice generation — all from within your workflows. Works with both PayPal Sandbox (for testing) and Production environments.

Prerequisites

Before adding a PayPal node to your workflow, you need two things from your PayPal Developer account:

• A PayPal Client ID

• A PayPal Client Secret

You also need to decide whether you are connecting to Sandbox (for testing) or Production (for live payments). Both environments have separate credentials.

Step 1 — Create a PayPal App

1. Go to the PayPal Developer Dashboard at developer.paypal.com

2. Log in with your PayPal business account

3. Go to Apps & Credentials

4. Select either the Sandbox or Live tab depending on which environment you are setting up

5. Click Create App

6. Give it a name (e.g. "Syncaut") and select Merchant as the app type

7. Click Create App

Once created, you will see your Client ID and Client Secret on the app detail page.

⚠️ Important: Sandbox and Live credentials are completely separate. Your Sandbox Client ID and Secret will not work in Production and vice versa. Make sure you are copying from the correct tab.

Step 2 — Copy Your Credentials

On the app detail page:

• Client ID — visible directly on the page

• Client Secret — click Show to reveal it, then copy it immediately

⚠️ Store your Client Secret safely. While you can reveal it again from the dashboard, treat it like a password — do not share it or commit it to version control.

Step 3 — Add the Credential to Syncaut

PayPal credentials are stored as a JSON object containing the Client ID, Client Secret, and environment.

1. In Syncaut, go to your Workspace → Credentials

2. Click Add Credential

3. Select PayPal as the type

4. In the credential value field, paste the following JSON — replacing the placeholder values with your actual credentials:

For Sandbox (testing):

{
  "clientId": "your_sandbox_client_id",
  "clientSecret": "your_sandbox_client_secret",
  "environment": "sandbox"
}

For Production (live payments):

{
  "clientId": "your_live_client_id",
  "clientSecret": "your_live_client_secret",
  "environment": "production"
}

5. Give it a recognisable name (e.g. "Client Store — PayPal Sandbox" or "Client Store — PayPal Live")

6. Save

⚠️ The credential must be valid JSON containing both clientId and clientSecret. The environment field defaults to sandbox if omitted, so make sure you explicitly set it to production for live payment processing. Mixing sandbox credentials with "environment": "production" or vice versa will cause authentication failures.

Your credentials are encrypted at rest and never exposed after saving.

Step 4 — Configure the PayPal Node

When adding a PayPal node to your workflow, you go through three steps:

Connect

• Step name — a variable name used to reference this node's output in later steps (e.g. createOrder). Must start with a letter or underscore, no spaces.

• Credential — select the PayPal credential you added above

Action

Choose what you want this node to do:

• Create order — Initiate a PayPal checkout and get an approval URL to redirect the customer to

• Capture order — Finalize a previously approved order and collect the payment

• Get order — Fetch the current status and details of an order

• Refund payment — Issue a full or partial refund on a captured payment

• Get payment — Fetch the details of a specific captured payment

• Create invoice — Generate a PayPal invoice for a customer

• Send invoice — Email a created invoice to the recipient

Payload

Each action comes with a pre-loaded JSON template. Replace the {{placeholders}} with actual values or reference outputs from previous workflow steps using {{stepName.data}}.

Actions Reference

Create Order

Initiates a PayPal payment order. Returns an approval URL that you redirect the customer to so they can log in to PayPal and approve the payment.

Key payload fields:

• intent — always CAPTURE for immediate payment

• purchase_units[0].amount.value — the payment amount as a string (e.g. "29.99")

• purchase_units[0].amount.currency_code — e.g. USD, GBP, EUR

• purchase_units[0].reference_id — your internal order ID for reference

• payment_source.paypal.experience_context.return_url — where PayPal redirects after approval

• payment_source.paypal.experience_context.cancel_url — where PayPal redirects if the customer cancels

After the node runs, the approval URL is available as {{stepName.approvalUrl}}. Redirect your customer to this URL to complete payment.

Capture Order

Finalizes an approved order and collects the funds. Must be called after the customer has approved the order on PayPal's side.

Key payload fields:

• orderId — required. The PayPal order ID returned from Create Order ({{createOrder.orderId}})

This action does not require a body — the order ID is all that is needed. Returns the completed transaction details.

Get Order

Fetches the current status and full details of a PayPal order.

Key payload fields:

• orderId — required. The PayPal order ID.

Useful for checking whether an order has been approved, captured, or is still pending.

Refund Payment

Issues a refund on a captured payment. Supports both full and partial refunds.

Key payload fields:

• captureId — required. The capture ID from the payment. Find it in the Capture Order response under {{captureOrder.data.purchase_units[0].payments.captures[0].id}}

• amount.value — the refund amount as a string. Omit this field for a full refund.

• amount.currency_code — must match the original payment currency

• note_to_payer — optional message shown to the customer

Get Payment

Fetches the details of a specific captured payment by its capture ID.

Key payload fields:

• captureId — required. The capture ID of the payment to look up.

Create Invoice

Generates a PayPal invoice and returns an invoice ID. The invoice is in draft state until you send it using the Send Invoice action.

Key payload fields:

• detail.invoice_number — your invoice reference number

• detail.invoice_date — date in YYYY-MM-DD format

• detail.currency_code — e.g. USD

• detail.payment_term.term_type — payment terms, e.g. NET_30, NET_15, DUE_ON_RECEIPT

• invoicer.email_address — your business email address

• primary_recipients[0].billing_info.email_address — the customer's email

• items[0].name — product or service name

• items[0].unit_amount.value — price per unit as a string

The invoice ID is available in the response as {{stepName.data.id}}.

Send Invoice

Emails a draft invoice to the recipient. Must be called after Create Invoice.

Key payload fields:

• invoiceId — required. The invoice ID returned from Create Invoice ({{createInvoice.data.id}})

• subject — the email subject line

• note — a message to include in the email body

• send_to_invoicer — set to true to also send a copy to your own email

Understanding the PayPal Payment Flow

A typical PayPal checkout automation in Syncaut follows this sequence:

1. Create Order — generates a PayPal order and approval URL

2. Redirect customer — send the customer to {{stepName.approvalUrl}} to approve the payment on PayPal's site

3. Customer returns — PayPal redirects back to your return_url with the order ID in the URL

4. Capture Order — call this with the order ID to finalize the payment and move funds

The Create Order and Capture Order steps are separate by design — PayPal requires customer approval between them.

Using Variables in the Payload

Reference outputs from previous workflow steps inside the payload using Handlebars syntax:

{{stepName.data}}

For example, if a previous step named getOrder fetched an order from your store, reference the order total as:

{{getOrder.data.total}}

Reference the capture ID from a completed PayPal capture:

{{captureOrder.data.purchase_units[0].payments.captures[0].id}}

Use the variable picker (+ variable) above the payload editor to insert common variables without typing them manually.

Referencing This Node's Output

Every PayPal node stores its result under the step name you provide. The full output structure is:

{
  "data": {},
  "action": "create_order",
  "orderId": "PAYPAL_ORDER_ID",
  "status": "CREATED",
  "approvalUrl": "https://www.paypal.com/checkoutnow?token=...",
  "links": []
}

• {{stepName.data}} — the full raw PayPal API response

• {{stepName.orderId}} — extracted PayPal order ID

• {{stepName.status}} — order status (e.g. CREATED, APPROVED, COMPLETED)

• {{stepName.approvalUrl}} — the URL to redirect the customer to (Create Order only)

• {{stepName.links}} — all HATEOAS links returned by PayPal

Sandbox vs Production

Syncaut uses the environment you specify in your credential JSON.

• Set "environment": "sandbox" to use api-m.sandbox.paypal.com — for testing only, no real money moves

• Set "environment": "production" to use api-m.paypal.com — live payments

Always test your full payment workflow in Sandbox before switching to Production. PayPal provides test buyer accounts in the Sandbox section of the Developer Dashboard to simulate customer approvals.

⚠️ If environment is not specified in your credential JSON it defaults to sandbox. Make sure you set it explicitly to production before going live or all payment requests will hit the sandbox and fail silently for real customers.

Troubleshooting

401 Unauthorized Your Client ID or Client Secret is incorrect, or you are using Sandbox credentials against a Production environment (or vice versa). Go to the PayPal Developer Dashboard, verify your app credentials, and check that the environment field in your credential JSON matches the tab you copied them from (Sandbox or Live).

PayPal credentials missing required fields Your credential JSON is missing clientId or clientSecret. Edit the credential in Workspace → Credentials and make sure both fields are present and correctly formatted.

orderId is required The orderId field in your payload is empty. Make sure you are passing the PayPal order ID from a previous Create Order step using {{stepName.orderId}}.

captureId is required The captureId field is empty. The capture ID comes from a completed Capture Order response. Reference it as {{captureOrder.data.purchase_units[0].payments.captures[0].id}}.

invoiceId is required The invoiceId field is empty in your Send Invoice payload. Reference the invoice ID from the Create Invoice step as {{createInvoice.data.id}}.

Invalid JSON payload The payload has a syntax error or an unresolved variable returned an unexpected value. Check the payload editor and make sure all {{placeholders}} are resolving correctly.

Credential not found The credential attached to the node was deleted from your workspace. Re-add it under Workspace → Credentials and update the node.

Status 204 with no response body Some PayPal actions return a 204 No Content response on success. Syncaut handles this automatically and returns { "status": "success" } in the output. This is expected behaviour for certain capture and send operations.