> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_paypals.md).

# Payment setting paypals

The payment setting paypal object and the allowed CRUD operations on the related resource endpoint

PayPal payment settings are the PayPal-specific subtype of [payment settings](https://docs.commercelayer.io/core-api-reference/2026-05/payment_settings.md). They hold the credentials and configuration required to process payments through [PayPal](https://www.paypal.com)'s REST API.

## Credentials

Setting up a PayPal payment setting requires the following credential attributes:

<table><thead><tr><th width="220">Attribute</th><th>Description</th><th width="100" data-type="checkbox">Required</th></tr></thead><tbody><tr><td><strong><code>client_id</code></strong></td><td>Your PayPal REST API client ID.</td><td>true</td></tr><tr><td><strong><code>client_secret</code></strong></td><td>Your PayPal REST API client secret.</td><td>true</td></tr><tr><td><strong><code>webhook_id</code></strong></td><td>The ID of the PayPal webhook pointing at <code>webhook_endpoint_url</code>, <a href="#webhook-management">generated automatically</a> — used to verify incoming <a href="#webhook-events">webhook</a> signatures. Read-only.</td><td>false</td></tr></tbody></table>

## Capabilities

PayPal payment settings support the following Commerce Layer features:

<table><thead><tr><th width="220">Feature</th><th width="100" data-type="checkbox">Supported</th><th>Notes</th></tr></thead><tbody><tr><td>Payment sessions</td><td>true</td><td></td></tr><tr><td>Payment wallets</td><td>true</td><td></td></tr><tr><td>Payment links</td><td>false</td><td></td></tr><tr><td>3DS / SCA</td><td>false</td><td>PayPal's own <a href="#approval-flow">approval step</a> provides equivalent strong customer authentication, but through a different mechanism — see below.</td></tr></tbody></table>

## Approval flow

{% hint style="info" %}
Unlike gateways that redirect the customer during authorization, PayPal requires the shopper's approval **before** an authorization can be attempted.
{% endhint %}

When a payment session is created with a PayPal payment setting, Commerce Layer creates a PayPal order and stores the raw response — including its HATEOAS `links` array — in the session's `response_data` attribute. Redirect the shopper to the link with the `rel` attribute set to `approve` to complete PayPal's approval step.

{% hint style="warning" %}
Because approval happens at session creation rather than during authorization, a PayPal payment authorization never transitions to `requires_action` — `next_action_type` and `next_action_data` stay `null` throughout its lifecycle. Attempting to authorize before the shopper has approved the order is rejected by PayPal.
{% endhint %}

Once the shopper returns from the approval step, create a [payment authorization](https://docs.commercelayer.io/core-api-reference/2026-05/payment_authorizations.md) as usual to complete the payment — or, if `auto_capture` is enabled, to authorize and capture it in one step.

## Wallet vaulting

PayPal vaulting uses a two-step token exchange. Your client-side integration (the PayPal JS SDK) collects the shopper's consent and produces a **setup token** — Commerce Layer never creates this token itself. Submit its ID back when creating the payment wallet, via the `_payment_details` trigger attribute:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "type": "payment_wallets",
    "attributes": {
<strong>      "_payment_details": { "setup_token_id": "..." }
</strong>    },
    "relationships": {
      "customer": { "data": { "type": "customers", "id": "..." } },
      "payment_setting": {
        "data": { "type": "payment_setting_paypals", "id": "..." }
      }
    }
  }
}
</code></pre>

Commerce Layer exchanges the setup token for a permanent payment token via PayPal's Vault API and stores it as the wallet's `payment_token`. Unless you supply your own `customer_token`, Commerce Layer sends the customer's own identifier alongside the setup token in that same request and stores it as the wallet's customer token — it's a separate input, not part of the token exchange itself.

{% hint style="info" %}
You can find more information about how this compares to the other payment providers [here](https://docs.commercelayer.io/core-api-reference/2026-05/payment_wallets.md#token-references).
{% endhint %}

### Vaulting during a payment

When a [payment session](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#vaulting-during-a-charge) has vaulting enabled, Commerce Layer asks PayPal to store the shopper's account once the payment succeeds, and creates the wallet from the vault token PayPal returns — no setup token is needed. PayPal can store the account right away, in which case the wallet is created with the authorization, or complete the payment first and store the account shortly after: the wallet is then created when the `VAULT.PAYMENT-TOKEN.CREATED` [webhook event](#webhook-events) arrives.

{% hint style="warning" %}
PayPal only vaults the account when reference transactions are enabled on your PayPal merchant account — otherwise the session is paid all the same, but no wallet is created.
{% endhint %}

### Duplicate wallets

PayPal keeps one vault token per PayPal account and customer, and returns the same one when that account is vaulted again for the same PayPal customer. Commerce Layer stores the PayPal customer ID on each wallet and reuses it for every later vaulting of that customer, directly or during a payment. The IDs sent to PayPal depend on how the wallet is created:

* **Created directly** — your own customer ID is always sent as the merchant reference, together with the PayPal customer ID once the customer has one.
* **Created during a payment** — your own customer ID is sent only until PayPal has assigned the customer an ID of its own. From then on, only the PayPal customer ID is sent.

{% hint style="info" %}
When a payment session with vaulting enabled vaults an account the customer already holds in an active wallet, the session is linked to that wallet instead of creating a new one.
{% endhint %}

{% hint style="warning" %}
Creating a wallet directly for an account that's already stored in one of the customer's active wallets is rejected, with a `422 Unprocessable Entity` error pointing to the existing wallet.
{% endhint %}

## Webhook management

When a PayPal payment setting is created, Commerce Layer automatically registers a webhook with PayPal, subscribed to the events below and pointing to `webhook_endpoint_url`, and stores the resulting `webhook_id`. If a webhook with the same URL already exists on the PayPal app, it is reused instead of creating a new one, and its subscriptions are updated to the events below. If the request fails — e.g. because the client credentials lack the necessary permissions — the payment setting is still created, but stays in the `pending` status until the webhook is provisioned (more details [here](https://docs.commercelayer.io/core-api-reference/2026-05/payment_settings.md#webhook-provisioning)). The webhook is removed from PayPal when the payment setting is deleted.

## Webhook events

Commerce Layer listens to the following PayPal webhook events, sent to the `webhook_endpoint_url` attribute exposed on this resource (more details [above](#webhook-management)):

<table><thead><tr><th width="330">Event</th><th>Action</th></tr></thead><tbody><tr><td><strong><code>PAYMENT.AUTHORIZATION.CREATED</code></strong></td><td>Creates or updates a payment authorization — <code>succeeded</code> or <code>failed</code>.</td></tr><tr><td><strong><code>PAYMENT.AUTHORIZATION.VOIDED</code></strong></td><td>Creates or updates a payment void — <code>succeeded</code>.</td></tr><tr><td><strong><code>PAYMENT.CAPTURE.COMPLETED</code></strong></td><td>Creates or updates a payment capture — <code>succeeded</code>.</td></tr><tr><td><strong><code>PAYMENT.CAPTURE.PENDING</code></strong></td><td>Creates or updates a payment capture — <code>succeeded</code>, recorded while PayPal is still holding the funds (e.g. for an eCheck or a payment under review).</td></tr><tr><td><strong><code>PAYMENT.CAPTURE.DENIED</code></strong></td><td>Creates or updates a payment capture — <code>failed</code>. A capture that's already <code>succeeded</code> is moved to <code>failed</code>.</td></tr><tr><td><strong><code>PAYMENT.CAPTURE.DECLINED</code></strong></td><td>Creates or updates a payment capture — <code>failed</code>. A capture that's already <code>succeeded</code> is moved to <code>failed</code>.</td></tr><tr><td><strong><code>PAYMENT.CAPTURE.REFUNDED</code></strong></td><td>Creates or updates a payment refund — <code>succeeded</code> — against the capture it refunds.</td></tr><tr><td><strong><code>PAYMENT.REFUND.PENDING</code></strong></td><td>Creates or updates a payment refund — <code>succeeded</code>, recorded while PayPal is still processing it — against the capture it refunds.</td></tr><tr><td><strong><code>PAYMENT.REFUND.FAILED</code></strong></td><td>Creates or updates a payment refund — <code>failed</code>. A refund that's already <code>succeeded</code> is moved to <code>failed</code>.</td></tr><tr><td><strong><code>VAULT.PAYMENT-TOKEN.CREATED</code></strong></td><td>Creates a <code>succeeded</code> payment wallet linked to the payment session that asked for vaulting, if it doesn't have one yet.</td></tr></tbody></table>

Events are matched to a payment session using the originating order ID — the same value Commerce Layer stores as the session's `token` — which PayPal sets in the event resource's `supplementary_data.related_ids.order_id` field for payment events, and in its `metadata.order_id` field for `VAULT.PAYMENT-TOKEN.CREATED`. When a payment event doesn't carry the order ID, Commerce Layer falls back to the event resource's `custom_id` — set to the payment session ID on every PayPal capture and refund it creates — and then to the capture referenced by the event's `up` link. If the referenced transaction does not already exist, it is created automatically.

With several partial captures on the same session, a refund event is attached to the capture it refunds, as referenced by its `up` link, or to the latest capture if that link is missing.

The custom ID is reserved for reconciliation: on captures and refunds, a value passed via the [transaction's](https://docs.commercelayer.io/core-api-reference/2026-05/payment_transactions.md#gateway-options) gateway options is always replaced by the payment session ID.

{% hint style="info" %}
Unlike Adyen, Braintree, and Checkout.com, PayPal has no local signature check based on a shared secret. Commerce Layer verifies every incoming event with a server-to-server call to [PayPal's own verification endpoint](https://developer.paypal.com/api/rest/webhooks/rest/) before processing it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_paypals.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
