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.

Accept PayPal payments through REST API v2

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.

Accept PayPal payments through Payflow Pro

Where to find it: Admin → Payment V2 → Add Processor → PayflowPro

When you'd use this: When you want to accept credit card payments through PayPal's Payflow Pro hosted checkout page, with the option to authorize and capture separately or capture immediately at checkout.

What you need first:

• A PayPal Payflow Pro account
• Partner login (typically "paypal" for standard accounts)
• Merchant login (your Payflow Pro merchant account username)
• User login (may be the same as merchant login)
• Password for API access
• Decision on whether to use pilot (testing) or production environment

Set it up:

1. In the CommerceBuild admin, navigate to Payment V2 and add a new processor.
2. Select PayflowPro as the processor type.
3. Enter your Payflow Pro credentials:
   • Partner (typically "paypal")
   • Vendor (your merchant login)
   • User (your API user login)
   • Password
4. Set the environment URL: use https://pilot-payflowpro.paypal.com for testing or https://payflowpro.paypal.com for production.
5. Configure your transaction type: Sale (immediate capture) or Authorization (hold funds for later capture).
6. Optionally configure a custom checkout template and return URL for your hosted payment page.
7. Save the processor configuration.

Using it day-to-day:

1. When a customer initiates checkout, the system calls createSecureToken with the transaction amount, currency, and optional billing address (street and ZIP for address verification).
2. The system generates a unique secure token ID for this payment session and receives back a secure token from Payflow Pro.
3. The customer is redirected to PayPal's hosted checkout page using the secure token.
4. After the customer completes payment, the system verifies the result server-to-server by calling inquireTransaction using a unique reference ID — this ensures the payment outcome can't be spoofed by replaying a different transaction's result.
5. For Sale transactions, funds are captured immediately. For Authorization transactions, you can later call capturePayment to capture the authorized amount.
6. You can void an authorized or captured payment by calling cancelPayment with the transaction reference.

Troubleshooting:

• Field format error: ORIGID missing — The inquiry transaction requires either a PNREF (transaction reference) or CUSTREF (customer reference). The system automatically generates and tracks these values during token creation.
• Authorization expires before capture — Payflow Pro authorizations typically expire after a set period (check your merchant agreement). Capture authorized funds promptly to avoid expiration.
• Address verification returns AVS mismatch — If you provide billing street and ZIP during token creation, Payflow Pro automatically runs address verification. The results (AVSADDR and AVSZIP) are recorded but not automatically enforced — review them manually or configure business rules based on your risk tolerance.
• Cannot inquire inquiries — The inquiry operation looks up the original transaction, not subsequent inquiry calls. The system automatically extracts the original result (ORIGRESULT) and transaction reference (ORIGPNREF) from the inquiry response.
• Secure token reuse fails — Secure tokens are single-use only. Each new payment attempt requires a fresh createSecureToken call with a new unique token ID.