PayPal

PayPal is a payment processor that enables stores to accept credit card and alternative payment transactions during checkout and invoice payment flows. The integration uses PayPal's REST API v2 to create orders, authorize payments, and capture funds.

How to set it up

Where to find it: Admin → Payments → PayPal

When you'd use this: When you want to accept PayPal payments, credit cards, or alternative payment methods through PayPal's checkout flow at point of purchase or when customers pay invoices.

What you need first:

• A PayPal business account
• Client ID and Secret from your PayPal Developer Dashboard (https://developer.paypal.com/)
• Decision on whether to use sandbox (testing) or production environment

Set it up:

1. Log into your PayPal Developer Dashboard and create a REST API app to obtain your Client ID and Secret.
2. Base64-encode your credentials in the format ClientID:Secret — this becomes your authorization credentials.
3. In the CommerceBuild admin, navigate to Payments → PayPal.
4. Enter your base64-encoded credentials.
5. Set the base URL: use https://api-m.sandbox.paypal.com for testing or https://api-m.paypal.com for production.
6. Configure your intent (CAPTURE for immediate payment, AUTHORIZE for two-step authorization/capture).
7. Enable the integration and save.

Configuration options

Field	What it does	Default	Required
credentials	Base64-encoded ClientID:Secret used for OAuth authentication	None	Yes
intent	Payment intent — either CAPTURE (immediate) or AUTHORIZE (hold funds for later capture)	None	Yes
accessToken	OAuth access token retrieved automatically from PayPal	Generated by getAccessToken operation	No (system-managed)
orderId	PayPal order identifier returned after order creation	Generated by createOrder operation	No (system-managed)
reference	Internal reference ID for the purchase unit	Provided at transaction time	Yes
invoiceId	Invoice identifier for the transaction	Provided at transaction time	Yes
currency	Three-letter ISO currency code (e.g., USD, EUR, GBP)	None	Yes
amount	Transaction amount as a decimal string	None	Yes
billTo	Billing address object containing firstName, lastName, email, addressLines (array), city, state, postCode, country	None	No
shipTo	Shipping address object containing name, addressLines (array), city, state, postCode, country	None	No

Using it day-to-day

1. When a customer initiates checkout or pays an invoice, the system calls getAccessToken to obtain an OAuth bearer token using your configured credentials.
2. The system calls createOrder with billing/shipping information (if provided), invoice details, and transaction amount to create a PayPal order.
3. The customer is redirected to PayPal to complete authentication and approve the payment.
4. After customer approval, the system calls either authorize (for two-step flows) or capture (for immediate payment) depending on your configured intent.
5. If the invoice ID changes after order creation, the system can call updateOrder to patch the order reference with the new invoice ID.
6. Authorization IDs and capture IDs are returned in the API response and stored for reference and potential refunds.

Troubleshooting

• "Invalid shipping Contact Phone" error during checkout: PayPal requires a phone number when shipping information is provided. Ensure your checkout flow captures and includes the customer's phone number in the shipping address object, or set shipping_preference to NO_SHIPPING if physical shipping is not required.
• 401 Unauthorized errors: Your base64-encoded credentials may be incorrect or expired. Verify that your Client ID and Secret are current and correctly encoded. Check that you're using the right environment (sandbox vs. production).
• Order creation fails with address validation errors: PayPal has strict address format requirements. Ensure country uses ISO 3166-1 alpha-2 codes (e.g., US, GB) and state uses standard abbreviations where applicable.
• Capture fails after authorization: Authorizations expire after a period (typically 3 days for PayPal). Ensure you capture authorized funds within the authorization window.
• Invoice ID mismatch: If your invoice ID is generated after order creation, use the updateOrder operation to patch the PayPal order with the correct invoice reference before finalizing the transaction.