PayPal
PayPal is a widely used digital payments platform that allows businesses to accept PayPal payments, including PayPal Checkout and Pay Later options.
| Payment method | Recurring payments | Recurring retries | Delayed capture | Partial refunds |
|---|---|---|---|---|
| PayPal | 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.
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
- Create a PayPal Developer account if you don't already have one.
- Navigate to Apps & Credentials and create a new REST API app (or use an existing one).
- 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 |
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.
Reference Transactions must be enabled on your PayPal account to use the Billing Agreement flow. Contact PayPal support to enable this feature.
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.
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.