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 (422): Verify the customer has approved the payment in the PayPal UI.
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.

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