Getting started with Pinch n8n integration

Prerequisites

Before you begin, you'll need:

• An n8n instance (self-hosted or n8n Cloud)
• A Pinch Payments account
• API credentials from your Pinch dashboard

Step 1: Install the Pinch Nodes

1. Go to Settings → Community Nodes
2. Click Install a community node
3. Enter n8n-nodes-pinch and click Install
4. Restart n8n if prompted

Step 2: Get Your Pinch API Credentials

1. Log in to your Pinch Dashboard
2. Navigate to API Keys
3. Create a new Application (if you haven't already)
4. Copy your Application ID and Secret Key

⚠️

Important: Use Development keys for testing and Live keys for production. Development keys work with the test API and won't process real payments.

Step 3: Configure Credentials in n8n

1. In n8n, go to Credentials → Add Credential
2. Search for and select Pinch API
3. Enter your credentials:
   • Application ID: Your Pinch Application ID
   • Secret Key: Your Pinch Secret Key
   • Environment: Select Test for development or Live for production
4. Click Save - n8n will automatically test the connection

Step 4: Create Your First Workflow

Example 1: Create a Payer and Payment Link

This workflow creates a new payer and generates a payment link for them.

1. Create a new workflow
2. Add a Manual Trigger node (or any trigger you prefer)
3. Add a Pinch node and configure:
   • Credential: Select your Pinch API credential
   • Resource: Payer
   • Operation: Create
   • Full Name: Enter the payer's name (e.g., John Smith)
   • Email Address: Enter their email (e.g., [email protected])
4. Add another Pinch node connected to the first:
   • Resource: Payment Link
   • Operation: Create
   • Amount: Enter amount in cents (e.g., 5000 for $50.00)
   • Payer ID: Use expression {{ $json.id }} to reference the created payer
   • Description: Invoice Payment
   • Return URL: Your thank-you page URL
   • Allowed Payment Methods: Select Credit Card and/or Bank Account
5. Execute the workflow

The output will include a url field - this is the payment link you can send to your customer.

Example 2: Listen for Payment Events

This workflow triggers when payments are processed.

1. Create a new workflow
2. Add a Pinch Trigger node:
   • Credential: Select your Pinch API credential
   • Events: Select Realtime Payment and Bank Results
3. Add any nodes to process the payment data (e.g., send email, update database)
4. Activate the workflow

Once activated, n8n will automatically register a webhook with Pinch. When payments are processed, your workflow will receive the event data.

Example 3: Retrieve Payer Information

This workflow looks up a payer and their payment history.

1. Create a new workflow
2. Add a trigger (Manual, Schedule, Webhook, etc.)
3. Add a Pinch node:
   • Resource: Payer
   • Operation: Get
   • Payer ID: The payer's ID (e.g., pyr_abc123)
4. Add another Pinch node:
   • Resource: Payment
   • Operation: For Payer
   • Payer ID: {{ $json.id }} or the same payer ID
5. Execute to retrieve the payer's details and payment history

Common Use Cases

Automated Invoice Payments

1. Trigger when an invoice is created in your system
2. Create a payer (or look up existing)
3. Create a payment link with the invoice amount
4. Send the payment link via email

Payment Notifications

1. Use Pinch Trigger to listen for Realtime Payment events
2. When a payment is received, send a confirmation email
3. Update your database or CRM with the payment status

Subscription Management

1. Listen for Subscription Created, Subscription Cancelled, and Subscription Complete events
2. Sync subscription status with your application
3. Trigger onboarding or offboarding workflows

Failed Payment Handling

1. Listen for Bank Results events
2. Check for dishonoured payments
3. Send retry notifications or update customer records

Tips and Best Practices

Testing

• Always use Development/Test credentials when building workflows
• Pinch provides test card numbers and bank accounts for testing
• Check the Pinch Testing Guide for test credentials

Error Handling

• Enable Continue on Fail in Pinch nodes to handle errors gracefully
• Use an IF node to check response status and branch accordingly
• Log errors to track failed API calls

Pagination

When listing payers or payment links:

• Use the Page and Page Size parameters to paginate through large result sets
• Maximum page size is 500 items

Webhooks

• Webhooks are automatically managed by the Pinch Trigger node
• Activating a workflow creates the webhook; deactivating deletes it
• You can select multiple events per trigger or use "All" to receive everything

Troubleshooting

Credentials Test Fails

• Double-check your Application ID and Secret Key
• Ensure you're using the correct environment (Test vs Live)
• Verify your Pinch account is active

Webhook Not Receiving Events

• Make sure your workflow is Activated (not just saved)
• Check that your n8n instance is publicly accessible (webhooks require a public URL)
• Verify the events are actually occurring in Pinch

Payment Link Not Working

• Ensure the payer ID exists in Pinch
• Check that the amount is in cents (not dollars)
• Verify the return URL is valid

Next Steps

• Explore the Pinch API Documentation for more details on each endpoint
• Check out the n8n Documentation for workflow building tips
• Join the n8n Community for help and inspiration