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.

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. 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.

Retries always use the gateway profile of the first attempt; see Configure a Payment Retry Policy. Capture can be delayed by up to 15 days; see PayPal payment settings.

PayPal account setup

1. Create a PayPal Developer account 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

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.

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.
   • 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. 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 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 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.