Paddle integration overview

Overview

Paddle is a merchant of record and billing platform for software and digital product companies. It handles payments, sales tax, subscriptions, and invoicing on behalf of sellers, letting teams manage customers, products, prices, and transactions from a single account. Persona’s Paddle integration allows you to create and update transactions and look up customer and product records — all directly from your Persona workflows, so billing actions can be triggered or informed by identity verification outcomes.

Benefits

Gate Billing on Verification: Create or update a Paddle transaction only after a Persona verification passes, keeping unverified customers out of your billing pipeline.

Keep Transactions Accurate: Update an existing transaction’s items, currency, or collection mode from a workflow when a case or verification outcome changes.

Look Up Customer and Product Context: Retrieve customer and product records from Paddle to inform decisions in a Persona workflow without leaving the platform.

Support Both Environments: Test end-to-end in Paddle’s sandbox before pointing your credential at the live environment.

Integration Features

Persona’s Paddle integration enables automation across transaction, customer, and product workflows. Key capabilities include:

• List Transactions: Return a paginated, filterable list of transactions.
• Create a Transaction: Create a new transaction with one or more catalog items.
• Update a Transaction: Update an existing transaction by its ID.
• List Customers: Return a paginated, filterable list of customers.
• Get a Customer: Retrieve a single customer by ID.
• List Products: Return a paginated, filterable list of products.
• Get a Product: Retrieve a single product by ID.

Setting up the Paddle integration

Prerequisites

To set up the Paddle integration, ensure you have:

• A Paddle account (live or sandbox)
• A Paddle API key with access to Transactions, Customers, and Products

Setting up the Paddle credentials

1. In the Persona Dashboard, navigate to Integrations > Marketplace and click on Paddle.
2. Click on Add Credential at the top of the page.
3. Enter a Nickname for Credential in the modal, along with your Paddle API key, and click Continue.
4. Once complete, the credential will appear in Persona and can be selected in workflows.

Using the Paddle integration in a workflow

1. Create a new workflow, or open an existing workflow you’d like to update.
2. Add a new action step > Integrations.
3. Select the Paddle integration and choose your Paddle credential.
4. Select the operation you want to run and map Persona data into the input fields.
5. Save and publish the workflow.

Paddle Operations Overview

Persona supports multiple Paddle API operations for managing transactions, customers, and products. These actions allow you to automate billing actions and look up account context based on Persona identity events.

See below for a comprehensive list of available Workflow Action steps and possible configurations for the Paddle integration:

List Transactions

Retrieve a paginated, filterable list of transactions.

Configuration Steps:

• No required fields.
• Optionally add:
  • Transaction ID, Customer ID, Subscription ID
  • Status, Collection Mode
  • Invoice Number, Billed At
  • Order By, Per Page, After (cursor)

Create a Transaction

Create a new transaction with one or more catalog items.

Configuration Steps:

• Provide values for required fields:
  • Items (array — each item requires Price ID and Quantity)
• Optionally add:
  • Status
  • Customer ID, Address ID, Business ID
  • Currency Code (must be USD if Collection Mode is manual)
  • Collection Mode
  • Discount ID
  • Custom Data

Update a Transaction

Update an existing transaction by its ID.

Configuration Steps:

• Provide values for required fields:
  • Transaction ID
• Optionally add:
  • Status
  • Customer ID, Address ID, Business ID
  • Currency Code, Collection Mode
  • Discount ID, Custom Data
  • Items (array — each item requires Price ID and Quantity)

List Customers

Retrieve a paginated, filterable list of customers.

Configuration Steps:

• No required fields.
• Optionally add:
  • Customer ID, Email, Search, Status
  • Order By, Per Page, After (cursor)

Get a Customer

Retrieve a single customer by ID.

Configuration Steps:

• Provide values for required fields:
  • Customer ID

List Products

Retrieve a paginated, filterable list of products.

Configuration Steps:

• No required fields.
• Optionally add:
  • Product ID, Status, Type, Tax Category
  • Include (related resources)
  • Order By, Per Page, After (cursor)

Get a Product

Retrieve a single product by ID.

Configuration Steps:

• Provide values for required fields:
  • Product ID
• Optionally add:
  • Include (related resources)

FAQs

Can I test this integration before going live?

Yes. Paddle exposes separate live (api.paddle.com) and sandbox (sandbox-api.paddle.com) environments — use a sandbox API key while testing your workflow.

What currency should I use when Collection Mode is manual?

Currency Code must be USD when Collection Mode is set to manual; other collection modes support other ISO 4217 currency codes.