# PayPal

PayPal is a widely used digital payments platform that allows businesses to accept PayPal payments, including PayPal Checkout and Pay Later options. A PayPal gateway profile can also process card payments; see [Card payments](#card-payments).

| Payment method | Recurring payments | Recurring retries | Delayed capture | Partial refunds |
| -------------- | ------------------ | ----------------- | --------------- | --------------- |
| PayPal         | Yes                | Yes               | Yes             | Yes             |
| Card           | Yes                | Yes               | Yes             | Yes             |

Recurring payments charge the PayPal account the customer approved during an earlier checkout, in both [integration modes](#integration-modes). A merchant-initiated payment for a customer with no approved PayPal account is declined, because PayPal requires the customer to approve the first payment.

Recurring card payments charge the saved card, linked to an earlier approved payment on it; see [Merchant-initiated card payments](#merchant-initiated-card-payments).

Retries always use the gateway profile of the first attempt; see [Configure a Payment Retry Policy](https://docs.odus.com/docs/guides/subscriptions/retry-policy.md). Capture can be delayed by up to 15 days; see [PayPal payment settings](https://docs.odus.com/docs/guides/dashboard/merchant-configuration.md#paypal-payment-settings).

## PayPal account setup

1. Create a [PayPal Developer account](https://developer.paypal.com/) if you don't already have one.
2. Navigate to **Apps & Credentials** and create a new REST API app (or use an existing one).
3. Copy the **Client ID** and **Secret Key** from your app's credentials.

## Gateway profile setup

| Field                    | Required | Description                                                                          |
| ------------------------ | -------- | ------------------------------------------------------------------------------------ |
| Integration              | Yes      | PayPal                                                                               |
| Environment              | Yes      | Must match the mode of your PayPal app credentials                                   |
| Client ID                | Yes      | Client ID from the PayPal Developer Dashboard                                        |
| Secret Key               | Yes      | Secret key from the PayPal Developer Dashboard                                       |
| Integration Mode         | Yes      | `vault` or `billingAgreement` — cannot be changed after creation                     |
| Webhook ID               | No       | Webhook ID from the PayPal Developer Dashboard, used for signature verification      |
| Collect Shipping Address | No       | Whether to collect the shipping address from PayPal. Only available for `vault` mode |
| Card Processing          | No       | Whether this profile also accepts card payments. See [Card payments](#card-payments) |

## Statement descriptors

PayPal adds the payment's statement descriptor suffix after `PAYPAL *` and the descriptor in your PayPal account, then cuts the line at 22 characters. Give your products a short statement descriptor suffix so it is not cut off. A payment without a suffix sends its full statement descriptor instead. See [Statement descriptors](https://docs.odus.com/docs/guides/products/overview.md#statement-descriptors).

## Credential verification

When you create or update the gateway profile, ODUS verifies the **Client ID** and **Secret Key** against PayPal before saving. If verification fails, the profile is not saved and an error is returned.

## Integration modes

PayPal supports two integration modes, chosen at gateway profile creation. The integration mode **cannot be changed** after the profile is created.

### Vault

Uses PayPal's Vault API to tokenize payment sources. The purchase amount is displayed on the PayPal checkout screen. This mode supports the **Collect Shipping Address** option, which retrieves the customer's shipping address from their PayPal account during checkout.

### Billing Agreement

Uses PayPal's Billing Agreement API to establish a consent-based payment agreement with the customer. Unlike Vault, the purchase amount is **not** displayed on the PayPal checkout screen, and collecting shipping addresses is **not** supported.

warning

Reference Transactions must be enabled on your PayPal account to use the Billing Agreement flow. Contact PayPal support to enable this feature.

## Card payments

A PayPal gateway profile can process card payments as well as PayPal payments. The customer enters their card in your checkout, and PayPal authorizes or captures it in the same request. A card that needs 3-D Secure takes one extra step, described below.

1. Ask PayPal to enable card processing on your PayPal account. Without it, PayPal declines every card payment.

2. Turn on card processing for the profile. Do one of these:

   <!-- -->

   * In the Dashboard, select **Accept card payments** on the profile; see [Gateway profiles](https://docs.odus.com/docs/guides/dashboard/gateway-profiles.md#paypal).
   * With API v2, send `configuration.cardProcessing: true` to `POST /v2/gateway-profiles`, or to `POST /v2/gateway-profiles/{id}` for an existing profile. API v1 does not accept the setting.

3. Point your card payment options at the profile, as you would for any card gateway.

ODUS sends the customer's billing address with the card when `billingAddress.country` is a two-letter ISO 3166-1 country code. Issuers use it to check the card, so a missing address can increase declines.

Turning card processing off removes card from the profile's supported payment methods. Card payment options that still point at the profile are declined with `merchant_configuration_error` until you point them at another gateway.

### 3-D Secure

ODUS asks PayPal for 3-D Secure when the card requires it, for example under strong customer authentication rules for cards issued in the EEA or the UK. Cards that don't need it are paid in one request, as above.

When a card needs it, the customer is redirected to their card issuer's challenge and then back to your Return URL, as with 3-D Secure on any other card gateway. Your checkout handles this as described in [3DS and redirect handling](https://docs.odus.com/docs/guides/checkout/3ds-and-redirect-handling.md). The payment is authorized or captured only after the customer returns.

If the issuer does not authenticate the customer, the payment is declined with `authentication_failed`, `authentication_rejected` or `authentication_unavailable`; see [Error codes](https://docs.odus.com/docs/guides/payments/error-codes.md) for what each one means. A customer who returns without completing the challenge is declined with `authentication_failed`.

### Merchant-initiated card payments

Subscription renewals, their retries and other merchant-initiated payments can charge a saved card through a PayPal profile. ODUS sends each one to PayPal as a payment from a stored card, linked to an earlier approved payment on the same card, and without the card's security code. No customer is present to take a challenge, so ODUS does not ask for 3-D Secure.

A merchant-initiated card payment is declined with `payment_method_unusable`, and is not sent to PayPal, when ODUS has nothing to link it to:

* the card has no earlier approved payment, on any gateway, that returned a card network reference,
* the card's brand is unknown, or
* the card is a Mastercard or Discover card, and ODUS does not have the date the card network approved the earlier payment. PayPal requires that date on these networks. ODUS records it only from payments taken through PayPal, so this applies to a card whose network reference came from a payment on another gateway.

Take the first payment with the customer present, through a PayPal profile, so that later payments have one to link to.

## Shipping address on saved-account payments

When ODUS charges a PayPal account the customer approved in an earlier checkout — a renewal, a retry or a merchant-initiated payment — it sends the customer's shipping address to PayPal with the payment, in both integration modes. PayPal Seller Protection for physical items covers a transaction only when you ship to the address on it, so ship these orders to the customer's shipping address.

The address is the customer's `shippingAddress`; see [Managing customers](https://docs.odus.com/docs/guides/customers/managing-customers.md) to set or update it. A shipping address PayPal rejects does not decline the payment: ODUS charges the account without it.

warning

ODUS sends the address only when `shippingAddress.country` is a two-letter ISO 3166-1 country code, such as `US` or `GB`, or PayPal's own `C2`. A customer with no country, or with a value such as `USA` or `United Kingdom`, is charged without a shipping address, and no error is returned.

The first payment is unchanged: the customer approves it on PayPal, and in Vault mode **Collect Shipping Address** retrieves the address the customer chooses there.