Ellipse Gradient for Header

PayPal Integration Guide

Connect PayPal payments, orders, payouts, subscriptions, invoices, disputes, and reporting with enterprise systems through REST APIs, OAuth 2.0, and selected webhook events.

PayPal integration options at a glance

PayPal’s primary integration model is its REST API portfolio, authenticated with OAuth 2.0 bearer tokens. The APIs support orders, payments, payouts, subscriptions, invoices, disputes, reporting, and webhook management. PayPal also provides webhook subscriptions for selected event types, while payout processing supports batch submission and later status retrieval. Reporting and transaction-search APIs support scheduled reconciliation without direct database access. Martini can obtain and manage PayPal tokens, consume these APIs, receive and verify webhook notifications, transform payloads, apply idempotency and business rules, and write results to applications or databases. Sandbox and live credentials can be isolated through protected environment configuration.

Integration pointSupported by PayPal?Common use casesHow Martini supports it
REST APIsYesPayPal REST APIs support orders, payments, payouts, subscriptions, invoicing, disputes, reporting, identity, and webhook management.Martini can consume PayPal REST APIs from workflows, map request and response data, expose standardized internal APIs, and apply validation, retries, and idempotency logic.
Webhooks / outbound callbacksYesPayPal supports webhook subscriptions and event notifications for selected payment, order, payout, subscription, dispute, and invoice events.Martini can expose an API endpoint or receive webhook events in a workflow, verify notifications, deduplicate event IDs, retrieve current resources, and route results.
Bulk / async / batch APIsLimitedPayouts support batch submission and later retrieval of batch and item statuses. Asynchronous behavior is product-specific rather than universal across PayPal resources.Martini can submit payout batches, persist batch identifiers, schedule status polling, and handle partial failures or delayed completion.
Reporting and transaction-search APIsYesReporting and transaction-search APIs support settlement reporting, financial monitoring, reconciliation, and scheduled extraction of supported account and transaction data.Martini can schedule paginated extraction, normalize results, retain checkpoints, and write data to databases or finance platforms.
AuthenticationYesPayPal REST APIs use OAuth 2.0 client credentials and bearer access tokens, with separate sandbox and live credentials and account-dependent permissions.Martini can obtain tokens, protect client credentials in secrets or environment configuration, and separate sandbox and production settings.
File / attachment APIsLimitedSome invoice-related operations may provide document or attachment capabilities, but no general-purpose PayPal file-transfer API was confirmed.Martini can process a confirmed product-specific endpoint when required, but attachment behavior should be validated for the exact API and account configuration.
SOAP APIsLegacyPayPal documents NVP/SOAP APIs as legacy technologies for older integrations.Martini can consume SOAP services where required, but new integrations should prefer PayPal REST APIs when the capability is available.
Database accessNoPayPal does not provide direct database access. Transaction and reporting data must be obtained through supported PayPal APIs.Martini can consume the reporting APIs and persist normalized results in a database or downstream finance system.

How PayPal exposes data and business events

PayPal REST APIs

PayPal REST APIs are the primary integration mechanism for orders, payments, payouts, subscriptions, invoices, disputes, reporting, identity, and webhook administration. Access requires OAuth 2.0 bearer tokens, and available operations depend on the PayPal product and account permissions.

Martini implementation pattern

Martini implementation pattern: a workflow obtains or reuses a PayPal access token, calls the required REST endpoint, validates the response, maps PayPal objects into an internal model, and writes the result to a target system or returns it through a Martini API. State-changing operations include correlation and idempotency controls.

Implementation sequence

Receive an API request or scheduled trigger
Obtain or reuse a PayPal OAuth 2.0 access token
Validate the request and current PayPal resource state
Call the required PayPal REST endpoint
Map and transform the response
Apply business rules and idempotency checks604?

PayPal Webhooks

PayPal supports webhook subscriptions and event notifications for selected order, payment, payout, subscription, dispute, and invoice events. Coverage is event-specific, so a webhook should not be assumed for every PayPal state change.

Martini implementation pattern

Martini implementation pattern: expose an API endpoint or webhook-consuming workflow, validate and verify the notification, persist the PayPal event ID, retrieve the current resource when the event payload is incomplete or ordering is uncertain, and route the normalized event downstream.

Implementation sequence

Receive the PayPal webhook notification
Validate the payload and event type
Verify webhook authenticity using PayPal’s verification procedure
Check and persist the PayPal event ID
Retrieve the related PayPal resource when required
Map the event to the downstream model

PayPal Payout Batches

PayPal payout APIs support submission of payout batches followed by retrieval of batch and item statuses. This is operation-specific asynchronous processing rather than a universal bulk API for all PayPal objects.

Martini implementation pattern

Martini implementation pattern: accept approved payout items, transform them into a PayPal payout batch, submit the batch, persist identifiers, and run a scheduled or event-driven status workflow that handles completed, failed, and partially completed items.

Implementation sequence

Receive approved payout items
Validate recipients, amounts, currencies, and duplicate controls
Submit the PayPal payout batch
Persist the batch and item identifiers
Retrieve batch and item statuses
Update the source finance or payroll system

PayPal Reporting APIs

PayPal reporting and transaction-search APIs provide supported account and transaction data for reconciliation, settlement reporting, and financial monitoring. They do not provide direct database access and commonly require pagination.

Martini implementation pattern

Martini implementation pattern: schedule a reporting workflow for a defined time window, retrieve all pages, normalize transactions and fees, persist a checkpoint, and compare PayPal results with internal orders, invoices, or settlement records.

Implementation sequence

Start the reporting workflow for a defined period
Request the first page of PayPal transaction data
Continue retrieving pages until completion
Normalize transactions, fees, currencies, and identifiers
Persist results and the extraction checkpoint
Flag unmatched or inconsistent transactions

Common PayPal integration patterns

Pattern 1: Orchestrate orders and payments

When to use this pattern

Use this pattern when a commerce platform or internal service needs to create, authorize, capture, refund, or cancel PayPal payments while retaining a consistent internal payment record. It is suitable for synchronous API-led processing with controlled retries and duplicate prevention.

Integration direction
Shopify
Martini
PayPal
Example Mapping
PayPal FieldCanonical FieldTarget Field
purchase_units[].amount.valueorder.totalAmountPayPal purchase unit amount
purchase_units[].amount.currency_codeorder.currencyPayPal currency code
merchant_reference_idorder.externalReferencePayPal custom reference
statuspayment.statusInternal payment status
Martini implementation pattern

A Martini API receives the commerce request and starts a workflow that validates amounts and currency, maps the order to a PayPal Orders request, obtains an OAuth token, and calls PayPal. The workflow stores Order and Capture IDs, returns the approval or capture result, and uses supported idempotency controls, bounded retries, and correlation identifiers for safe recovery.

Martini capabilities used
  • APIs
  • workflows
  • API consumption
  • OAuth 2.0 configuration
  • data mapping
  • business rules
  • error handling

Pattern 2: Synchronize PayPal webhooks

When to use this pattern

Use this pattern when downstream systems must react to selected PayPal payment, order, subscription, payout, invoice, or dispute events without relying only on scheduled polling. Because event coverage is selective and delivery can be duplicated or out of order, resource retrieval and reconciliation remain important.

Integration direction
PayPal
Martini
Salesforce
Example Mapping
PayPal FieldCanonical FieldTarget Field
idevent.externalIdSalesforce integration event ID
event_typeevent.typeSalesforce activity type
resource.idpaypalResource.idSalesforce PayPal reference
resource.statusresource.statusSalesforce payment or case status
Martini implementation pattern

Martini receives the webhook at an exposed API endpoint, validates and verifies the event, checks the event ID for prior processing, and retrieves the current PayPal resource when necessary. It then maps the normalized event to Salesforce or another target, records processing status, and returns a controlled response so PayPal redelivery does not create duplicate business actions.

Martini capabilities used
  • APIs
  • webhook consumption
  • workflows
  • data mapping
  • idempotency rules
  • business rules
  • error handling

Pattern 3: Submit and monitor payout batches

When to use this pattern

Use this pattern for approved groups of recipient payments that should be submitted as PayPal payout batches and monitored until each item reaches a terminal state. It is appropriate when payout completion is asynchronous or partial failures require operational review.

Integration direction
NetSuite
Martini
PayPal
Example Mapping
PayPal FieldCanonical FieldTarget Field
vendorPaymentIdpayout.itemReferencePayPal sender_item_id
amountpayout.amountPayPal payout amount
currencypayout.currencyPayPal currency
transaction_statuspayout.statusNetSuite payment status
Martini implementation pattern

A Martini workflow validates approved payouts, prevents duplicate submission using business references, maps them to a PayPal payout batch, and persists batch and item IDs. A scheduled workflow retrieves statuses, separates completed and failed items, applies bounded retry or exception rules, and updates the accounting system with full correlation context.

Martini capabilities used
  • workflows
  • scheduling
  • API consumption
  • data mapping
  • business rules
  • asynchronous orchestration
  • error handling

Pattern 4: Reconcile PayPal transactions and settlements

When to use this pattern

Use this pattern when finance teams need to compare PayPal transaction, fee, refund, payout, or settlement data with internal orders and invoices. It is suited to scheduled extraction and historical retention because PayPal does not provide direct database access.

Integration direction
PayPal
Martini
NetSuite
Example Mapping
PayPal FieldCanonical FieldTarget Field
transaction_idsettlement.paypalTransactionIdNetSuite external transaction ID
transaction_amount.valuesettlement.grossAmountNetSuite gross amount
fee_amount.valuesettlement.feeAmountNetSuite processing fee
transaction_statussettlement.statusNetSuite reconciliation status
Martini implementation pattern

A scheduled Martini workflow requests PayPal reporting data for a bounded period, follows pagination links or page indicators, normalizes decimal-safe amounts and currencies, and persists a checkpoint. It compares PayPal identifiers with internal orders and invoices, flags discrepancies, and writes accepted results to a finance platform or SQL database.

Martini capabilities used
  • scheduling
  • workflows
  • API consumption
  • pagination handling
  • data mapping
  • SQL/database integration
  • error handling

Applications commonly integrated with PayPal

PayPal is commonly connected to commerce, customer, finance, accounting, and operational platforms. Martini can coordinate these integrations through PayPal REST APIs, selected webhook events, scheduled reporting workflows, and reusable transformation and error-handling logic.

Application Scenario Direction Martini Pattern
Salesforce Synchronize PayPal payment activity, orders, refunds, subscriptions, and disputes with customer and service records. PayPal → Martini → Salesforce Receive selected PayPal webhook events or retrieve resources through REST APIs, normalize identifiers and monetary values, then create or update Salesforce records with duplicate detection and retry handling.
Shopify Connect Shopify orders and checkout activity with PayPal authorization, capture, refund, and reconciliation processes. Shopify → Martini → PayPal Accept commerce order data, map eligible orders to PayPal Orders requests, store PayPal Order and Capture IDs, and route status changes back to Shopify or an internal commerce service.
WooCommerce Process or reconcile PayPal payments for WooCommerce orders and maintain accurate payment status. WooCommerce → Martini → PayPal Orchestrate payment actions using PayPal REST APIs, correlate WooCommerce order identifiers with PayPal resources, and use webhook or scheduled reconciliation flows for completion and exception handling.
NetSuite Reconcile PayPal settlements, payouts, fees, refunds, and invoices with financial records. PayPal → Martini → NetSuite Schedule PayPal reporting and transaction-search calls, paginate through results, transform them into a finance model, and write normalized transactions while flagging unmatched or duplicated items.
QuickBooks Online Post PayPal transactions, fees, refunds, and settlement information into accounting records. PayPal → Martini → QuickBooks Online Extract PayPal reporting data for a defined period, apply chart-of-accounts and currency rules, and submit accounting entries with persistent PayPal identifiers for reconciliation.
Adobe Commerce Synchronize PayPal payment activity with Adobe Commerce orders, captures, refunds, and cancellations. Adobe Commerce → Martini → PayPal Map Adobe Commerce order actions to PayPal REST operations, validate the current PayPal resource state before changes, and return normalized outcomes to commerce workflows.
ServiceNow Create or update cases for payment disputes, failed payouts, webhook failures, and operational exceptions. PayPal → Martini → ServiceNow Route selected PayPal dispute, payout, and processing-error events through Martini, enrich them with current PayPal resource data, and create or update ServiceNow cases with correlation IDs.
Jira Create engineering or operations issues for recurring PayPal API failures, reconciliation exceptions, or webhook-processing incidents. PayPal → Martini → Jira Use Martini error and reconciliation workflows to classify recurring exceptions, attach PayPal identifiers and diagnostic context, and create Jira issues only when configured thresholds are exceeded.

How to build a PayPal integration in Martini

Objective

Configure PayPal sandbox and live environments with separate OAuth application credentials and protected secrets.

Instructions in Martini

  • Store the PayPal client ID, client secret, webhook verification values, and environment-specific base URLs in protected Martini configuration.
  • Configure OAuth 2.0 token acquisition and avoid hard-coding credentials or access tokens in workflows.
  • Validate that the PayPal application has the permissions required by the selected APIs.

Objective

Select an API request, PayPal webhook, scheduled workflow, or payout status trigger based on the business process.

Instructions in Martini

  • Use an exposed Martini API for synchronous payment or order operations.
  • Use PayPal webhook notifications for supported event types and a scheduler for reporting or asynchronous status checks.
  • Use scheduled reconciliation when a required state change is not covered by a PayPal webhook.

Objective

Obtain PayPal data through REST calls or verified webhook notifications and preserve identifiers needed for correlation.

Instructions in Martini

  • Acquire or reuse a valid PayPal OAuth access token before REST calls.
  • Validate webhook structure and verify authenticity before processing financial events.
  • Retrieve the current PayPal resource when event payloads are incomplete or events may be out of sequence.

Objective

Coordinate PayPal calls, downstream writes, state transitions, and asynchronous operations in a maintainable Martini workflow.

Instructions in Martini

  • Separate token handling, resource retrieval, transformation, business rules, and target writes into clear workflow stages.
  • Persist Order, Capture, Refund, Payout Batch, Invoice, Subscription, and Dispute identifiers where relevant.
  • Use bounded retries for transient failures and route non-retryable business or authorization errors for review.

Objective

Convert PayPal payloads into the canonical model required by commerce, CRM, finance, accounting, or operational systems.

Instructions in Martini

  • Map PayPal resource fields to the target model and preserve source identifiers and currency codes.
  • Use decimal-safe handling for monetary amounts and apply currency-specific precision rules.
  • Handle optional fields and product-specific response variations without assuming every field is present.

Objective

Validate resource state, idempotency, permissions, event coverage, and reconciliation conditions before committing changes.

Instructions in Martini

  • Check whether the requested PayPal operation is valid for the resource’s current state.
  • Persist webhook event IDs and business correlation IDs before non-idempotent downstream actions.
  • Flag unmatched transactions, partial payout failures, and unsupported account capabilities rather than silently dropping them.

Common PayPal data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
OrdersRepresents a buyer checkout order, including purchase units, amounts, payer information, and order status.Shopify, WooCommerce, Adobe Commerce, Salesforce, order databasesMartini maps internal order data to PayPal Orders requests, stores PayPal Order IDs, validates resource state, and synchronizes status changes.
PaymentsRepresents authorizations, captures, refunds, and related payment operations associated with orders.Salesforce, NetSuite, QuickBooks Online, commerce platformsMartini correlates authorization, capture, and refund identifiers, applies monetary precision rules, and routes webhook or API results to downstream systems.
PayoutsRepresents mass payments sent to recipients through payout batches and payout items.NetSuite, QuickBooks Online, payroll-related systems, databasesMartini submits approved payout batches, persists batch and item identifiers, polls asynchronous statuses, and handles partial failures.
InvoicesRepresents invoices issued to customers, including recipients, amounts, status, and payment actions.NetSuite, QuickBooks Online, Salesforce, finance databasesMartini maps invoice data, invokes supported invoice operations, processes selected events, and preserves invoice identifiers for reconciliation.
SubscriptionsRepresents recurring billing agreements and subscription plans.Salesforce, Shopify, customer databases, service platformsMartini synchronizes selected subscription events, retrieves current subscription resources when needed, and applies lifecycle and duplicate-processing rules.
DisputesRepresents disputes and claims associated with PayPal transactions.Salesforce, ServiceNow, NetSuite, JiraMartini receives supported dispute notifications or retrieves dispute data, enriches cases with transaction identifiers, and routes exceptions for operational follow-up.

Authentication and security considerations

OAuth 2.0 credentials

PayPal REST APIs use OAuth 2.0 client credentials and bearer access tokens. Client IDs, client secrets, tokens, and webhook verification values should be stored in Martini secrets or protected environment configuration.

Environment separation

Sandbox and live PayPal environments use different credentials and base URLs. Keep these values environment-specific and validate deployment configuration before enabling production calls.

Webhook verification

Webhook deliveries should be verified using PayPal’s supported verification procedure. Do not trust a notification solely because it reached the Martini endpoint.

Least privilege and protected APIs

PayPal permissions vary by application, account, product, and enabled capability. Exposed Martini APIs should use appropriate authentication and authorization controls and should not disclose PayPal credentials or raw sensitive responses unnecessarily.

Operational considerations for PayPal integrations

Rate limits and transient failures

Use bounded backoff for retryable failures and distinguish them from invalid requests, authorization failures, and business-state errors.

Pagination and checkpoints

Reporting and list endpoints may be paginated. Continue until PayPal indicates completion and persist checkpoints to avoid unbounded or repeated extraction.

Idempotency and ordering

Use PayPal-supported idempotency controls where available and persist webhook event IDs. Events can be duplicated, delayed, or out of order, so retrieve the current resource for important financial state changes.

State and asynchronous processing

Orders, captures, payouts, subscriptions, and disputes are stateful. Validate the current state before state-changing calls and treat payout completion as asynchronous where applicable.

Schema and monetary changes

Track the PayPal API contract used by each workflow, tolerate optional fields, test against sandbox responses, and represent amounts with decimal-safe values while preserving currency codes and precision.

Reconciliation

Persist PayPal Order, Capture, Refund, Payout Batch, Invoice, Subscription, and Dispute identifiers so support, retries, webhook handling, and financial reconciliation remain traceable.

Why use Martini instead of scripts or point-to-point integrations?

Centralized orchestration

Martini coordinates PayPal API calls, webhook handling, scheduled reporting, asynchronous payout monitoring, and downstream writes in workflows rather than scattering logic across scripts.

Reusable integration assets

OAuth handling, validation, mappings, resource retrieval, idempotency, retry rules, and error routing can be implemented as reusable integration logic and controlled through environment configuration.

Flexible enterprise connectivity

Martini can consume PayPal REST APIs, expose internal APIs, connect to databases and enterprise applications, and transform PayPal objects into canonical business models.

Operational reliability

Structured correlation, checkpoints, bounded retries, webhook verification, monitoring, and reconciliation provide stronger operational control than isolated point-to-point scripts.

Frequently asked questions

How can PayPal be integrated with enterprise systems?

PayPal can be integrated primarily through its REST APIs using OAuth 2.0 bearer tokens. Enterprise workflows can create and manage orders, payments, payouts, subscriptions, invoices, and disputes, consume reporting APIs, receive selected webhook events, and synchronize normalized data with commerce, CRM, finance, accounting, and operational systems.

Can Martini integrate with PayPal?

Yes. Martini can integrate with PayPal by consuming PayPal REST APIs, obtaining OAuth 2.0 access tokens, receiving selected PayPal webhook events, processing payout and reporting operations, and orchestrating mappings, business rules, retries, and downstream updates.

Do I need a connector to integrate PayPal with Martini?

No. A dedicated PayPal connector is not required. Martini can use PayPal’s confirmed native integration mechanisms, including REST APIs, OAuth 2.0 authentication, webhook notifications, reporting APIs, and operation-specific batch endpoints.

Is there any extra Lonti cost to integrate PayPal with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate PayPal. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from PayPal, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.

Which PayPal APIs and integration methods should be used?

New integrations should generally use PayPal REST APIs with OAuth 2.0. Webhooks are appropriate for selected supported events, reporting APIs support reconciliation, and payout APIs support batch submission and status retrieval. PayPal NVP/SOAP APIs are documented as legacy and should normally be avoided when REST coverage is available.

Can Martini receive PayPal webhooks and events?

Yes. PayPal supports webhook subscriptions and event notifications for selected event types. Martini can receive the notifications through an API endpoint or workflow, verify their authenticity, deduplicate event IDs, retrieve current resources when needed, and route normalized events to downstream systems. Webhook coverage is not universal across all PayPal state changes.

How should PayPal synchronization, mapping, and duplicate handling work?

Synchronization can combine real-time selected webhook events with scheduled retrieval and reporting workflows. Martini maps PayPal objects into canonical models, preserves PayPal resource identifiers, applies decimal-safe monetary transformations, and stores event or business correlation IDs. Resource retrieval and reconciliation help address delayed, duplicated, or out-of-order events.

How does Martini handle PayPal errors, retries, and API façades?

Martini can distinguish transient HTTP failures from validation, authorization, and business-state errors, then apply bounded retries and route unrecoverable exceptions for review. It can also expose a controlled internal API façade that standardizes PayPal operations for other applications while keeping OAuth handling, mappings, state checks, and PayPal-specific error behavior within reusable workflows.

Related Martini documentation

Martini APIs

Workflows

Security

Operations

Connect PayPal with your enterprise systems

Use Martini to orchestrate PayPal APIs, selected webhook events, payout workflows, and financial reconciliation across your enterprise applications.

EXPLORE MARTINI
BOOK A DEMO