PayPal Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The PayPal Checkout Adapter integrates PayPal's payment platform with Norce Checkout. This page focuses on the unique technical details and configuration for PayPal.

Supported payment methods and other features: Features Overview

Configuration in Norce Admin

The adapter is configured using the following settings in the apiSettings section:

Field	Description	Example Value
`apiUrl`	PayPal API URL (sandbox or live).	`https://api-m.sandbox.paypal.com`
`paypalMerchantId`	Your PayPal Merchant ID from Developer Dashboard.	`MERCHANT123`

Options Configuration

The options section contains adapter behavior settings:

Field	Description	Default Value
`intent`	Payment intent: `authorize` (reserve funds) or `capture` (immediate payment).	`authorize`
`providesCustomer`	If `true`, customer address comes from PayPal. If `false`, address is collected outside PayPal.	`false`
`mapDiscountPerRow`	If `true`, discounts are included in item prices. If `false`, discounts appear as separate order lines.	`false`
`useCartReferenceAsInvoiceId`	If `true`, uses `cart.reference` as PayPal invoice ID. If `false`, uses the Norce order reference.	`false`
`disableFunding`	Array of funding sources to disable (e.g., `["credit", "card"]`).	`[]`
`enableFunding`	Array of funding sources to enable (e.g., `["paylater", "venmo"]`).	`[]`
`paymentSource`	JSON string for advanced PayPal payment source configuration with return/cancel URLs.	`null`

Redirect URLs Configuration

When using PayPal as an external redirect flow (not SDK-based), configure the redirectUrls section:

Field	Description
`checkoutPage`	URL to redirect to if payment fails or is cancelled. Supports `{order.merchant}`, `{order.channel}`, `{order.id}`, and `{errorCode}` placeholders.
`confirmationPage`	URL to redirect to after successful payment authorization. Supports `{order.merchant}`, `{order.channel}`, and `{order.id}` placeholders.

PayPal API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), PayPal uses the following external API environments:

Environment	PayPal API Base URL
Production	`https://api-m.paypal.com`
Sandbox	`https://api-m.sandbox.paypal.com`

Webhook Configuration

Configure webhooks in PayPal Developer Dashboard with the following events:

CHECKOUT.ORDER.APPROVED
CHECKOUT.ORDER.COMPLETED
PAYMENT.AUTHORIZATION.CREATED

Webhook URL format:

https://{slug}.api-se.{env}.norce.tech/checkout/paypal-adapter/api/checkout/v1/callback/webhook

Creating a PayPal Payment

To initialize a PayPal Checkout session:

POST /api/v1/orders/{order_id}/payments
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The response includes SDK configuration for rendering PayPal buttons:

{
  "paymentId": "pVjGamNQMiEtecSfkABthgijIJK",
  "reference": "5O190127TN364715T",
  "sdkUrl": "https://api-m.sandbox.paypal.com",
  "partnerAttributionId": "Norce_Cart_PPCP",
  "sdkSettings": {
    "clientId": "AdfIh3vhZgRSn0CrYDXnbDOCwTUPnWZ...",
    "merchantId": "MERCHANT123",
    "currency": "SEK",
    "locale": "sv_SE",
    "buyerCountry": "SE",
    "disableFunding": [],
    "enableFunding": [],
    "commit": false,
    "vault": false,
    "integrationDate": "2025-04-01",
    "intent": "authorize"
  }
}

Handling Shipping Changes

The adapter supports shipping address and option change callbacks:

    POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-address-change
    Host: {slug}.api-se.stage.norce.tech

    POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-options-change
    Host: {slug}.api-se.stage.norce.tech

Troubleshooting (PayPal Specific)

In addition to the generic troubleshooting steps:

Payment Creation Fails (409 Conflict): A PayPal payment already exists for this order. Remove the existing payment or use a different order.
Authorization Fails (400 Bad Request): Verify the customer has approved the payment in the PayPal UI. The adapter returns 400, not PayPal's upstream 422.
Webhook Signature Invalid: Verify the webhook URL is correctly configured in PayPal Developer Dashboard.
Review transaction details in PayPal Developer Dashboard.
Verify webhook delivery status in PayPal.

PayPal Order Expiration

PayPal orders and authorizations have expiration windows enforced by PayPal's platform. The Norce Checkout PayPal Adapter does not proactively detect expiration — it returns a PayPal error when an operation is attempted on an expired resource.

PayPal Order Not Found (3-Hour Expiration)

A PayPal order expires after 3 hours if the buyer has not approved the payment. After expiration, PayPal no longer recognizes the order. The adapter may return either paypal-resource-not-found (HTTP 404) or paypal-order-expired (HTTP 400) depending on the PayPal SDK error.

What to do: Remove the expired PayPal payment from the Norce Checkout order and create a new PayPal payment. The existing PayPal order cannot be recovered after expiration.

PayPal Order Expiration Window

PayPal orders expire after 3 hours by default. PayPal supports extending this window up to 72 hours on the PayPal side. Contact your PayPal Account Manager (TAM) to configure an extended expiration window for your merchant account. This extension is configured in PayPal's platform, not in Norce Checkout.

PayPal Authorization Expiration (29-Day Window)

When using the authorize intent, a PayPal authorization is valid for 29 days. PayPal recommends capturing within the 3-day honor period for the highest capture success rate. After 29 days the authorization auto-voids and a new payment must be created.

The adapter does not explicitly map PayPal's AUTHORIZATION_EXPIRED error — an expired authorization surfaces as a generic paypal-error (HTTP 400). The Norce Checkout PayPal Adapter does not implement PayPal's reauthorization flow.

What to do: Create a new PayPal payment on the same Norce Checkout order. The expired authorization cannot be captured or reauthorized through the adapter.

Redirect Return Error Handling

When the customer returns from PayPal's redirect flow and the PayPal order is expired or not found, the Norce Checkout PayPal Adapter redirects the customer to the configured checkoutPage URL with an error code parameter:

Scenario	Redirect Error Code
PayPal order expired or not found	`order-not-found`
Order conflict (order changed since approval)	`order-conflict`
Payment error	`payment-error`
Internal server error	`internal-server-error`

The error code is substituted into the {errorCode} placeholder in the redirectUrls.checkoutPage URL. Integration partners should handle the order-not-found error code by removing the expired PayPal payment and creating a new one.

Payment States

State	Description
`intent`	Payment initialized, awaiting customer approval
`processing`	Payment approval in progress
`pending`	Awaiting asynchronous confirmation
`reserved`	Payment authorized successfully
`captured`	Payment captured (funds transferred)
`declined`	Payment declined by PayPal
`cancelled`	Payment voided/cancelled