Last updated

Norce Checkout - Paypal Adapter API

Version: 1.0.0

Build 2025-10-28 14:10:12

The Paypal Adapter API is used to create and manage a Paypal Order.

For conceptual documentation and usage guides, see:

Authentication

Bearer

  • Type: apiKey
  • Description: Authorization header using the bearer scheme. Example: 'Bearer a3bcdABCaB12abc3AbCDAB5AbcABCaBcABC5ab3c5A0='

Endpoints

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-address-change

Shipping address change. The Norce order will be updated with the latest selected shipping address from PayPal

Shipping address change. The Norce order will be updated with the latest selected shipping address from PayPal.

Parameters

  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string
  • merchant (query) required
    • Type: string
  • channel (query) required
    • Type: string

Request Body

Content-Type: application/json

Responses

200

OK

Content-Type: application/json

Schema: PaypalShippingAddressChangeResponse

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-options-change

Shipping options change. Updates order with the selected shipping option from PayPal

Handles shipping option changes from PayPal. Updates the order with the selected shipping option and returns updated pricing information.

Parameters

  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string
  • merchant (query) required
    • Type: string
  • channel (query) required
    • Type: string

Request Body

Content-Type: application/json

Responses

200

OK

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/address-changed

Address change hook

Responds to address changes in norce orders and updates PayPal order accordingly.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Content-Type: application/json

Responses

200

OK

Content-Type: application/json

Schema: Array of PatchOperation

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/state-changed

State Changed hook

Responds to state changes in norce orders.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Content-Type: application/json

Responses

200

OK

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/update-payment

Update payment hook

Responds to changes in norce orders and updates the amount in paypal.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Content-Type: application/json

Responses

200

OK

Content-Type: application/json

Schema: Array of PatchOperation

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

POST /api/checkout/v1/callback/webhook

Handles PayPal webhook events

Consumes PayPal webhook events and updates the Norce order accordingly.

Request Body

Content-Type: application/json

Responses

200

OK

Content-Type: application/json

Schema: Array of PatchOperation

400

Bad Request

Content-Type: application/json

404

Not Found

Content-Type: application/json

500

Internal Server Error

GET /api/checkout/v1/callback/orders/{order_id}/redirect-return

Handle return from PayPal redirect payment flow

Handles return from PayPal redirect payment flow and authorizes the order

Parameters

  • merchant (query) required
    • Merchant ID
    • Type: string
  • channel (query) required
    • Channel ID
    • Type: string
  • order_id (path) required
    • Order identifier
    • Type: string

Responses

303

See Other

POST /api/v1/orders/{order_id}/payments

Create a new Paypal order

Requires an existing Norce order.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Order identifier
    • Type: string

Responses

200

OK

Content-Type: application/json

Schema: PaypalOrder

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

409

Conflict

Content-Type: application/json

Schema: Error

GET /api/v1/orders/{order_id}/payment-sdk-settings

Get SDK settings for rendering PayPal without creating an order

Requires an existing Norce order. Returns SDK settings without PaymentId and Reference for frontend rendering.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Order identifier
    • Type: string

Responses

200

OK

Content-Type: application/json

Schema: PaypalOrder

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

409

Conflict

Content-Type: application/json

Schema: Error

GET /api/v1/orders/{order_id}/payments/redirect

Create a new Paypal order and redirect to the payment page

Requires an existing Norce order. This endpoint is idempotent

Parameters

  • merchant (query) required
    • Merchant
    • Type: string
  • channel (query) required
    • Channel
    • Type: string
  • order_id (path) required
    • Order identifier
    • Type: string

Responses

200

OK

Content-Type: application/json

Schema: PaypalOrder

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

409

Conflict

Content-Type: application/json

Schema: Error

GET /api/v1/orders/{order_id}/payments/{payment_id}

Get a Paypal payment

Requires an existing Norce order and payment.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Order identifier
    • Type: string
  • payment_id (path) required
    • Payment identifier
    • Type: string

Responses

200

OK

Content-Type: application/json

Schema: PaypalOrder

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

409

Conflict

Content-Type: application/json

Schema: Error

POST /api/v1/orders/{order_id}/payments/{payment_id}/remove

Remove a Paypal payment

Requires an existing Norce order and payment.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Order identifier
    • Type: string
  • payment_id (path) required
    • Payment identifier
    • Type: string

Responses

204

No Content

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

409

Conflict

Content-Type: application/json

Schema: Error

POST /api/v1/orders/{order_id}/authorize

Requires an existing Norce order.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

422

Unprocessable Content

Content-Type: application/json

Schema: Error

POST /api/v1/orders/{order_id}/capture

Requires an existing Norce order.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

422

Unprocessable Content

Content-Type: application/json

Schema: Error

POST /api/v1/orders/{order_id}/void

Requires an existing Norce order with authorized payment.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

422

Unprocessable Content

Content-Type: application/json

Schema: Error

POST /api/v1/orders/{order_id}/refund

Requires an existing Norce order with captured payment.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1
  • order_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

422

Unprocessable Content

Content-Type: application/json

Schema: Error

POST /api/v1/partner-referral

Requires registered webhook(s), so that we can receive the referral confirmation from PayPal.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1

Request Body

Content-Type: application/json

Responses

303

See Other

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

500

Internal Server Error

Content-Type: application/json

Schema: Error

GET /api/v1/partner-referral

Get the onboarding status of a PayPal merchant.

Parameters

  • x-merchant (header) required
    • Merchant identifier.
    • Type: string
    • Example: norce
  • x-channel (header) required
    • Channel identifier
    • Type: string
    • Example: 1

Responses

200

OK

Content-Type: application/json

Schema: MerchantOnboardingStatus

400

Bad Request

Content-Type: application/json

Schema: Error

404

Not Found

Content-Type: application/json

500

Internal Server Error

Content-Type: application/json

Schema: Error

Schemas

Addon

Properties

  • reference (string)
  • price (number)

Address

Properties

  • type
  • givenName (string)
  • familyName (string)
  • careOf (string)
  • reference (string)
  • organizationName (string)
  • streetAddress (string)
  • streetAddress2 (string)
  • postalCode (string)
  • city (string)
  • region (string)
  • country (string)
  • phone (string)
  • email (string)
  • nationalIdentificationNumber (string)
  • organizationIdentificationNumber (string)
  • attributes (object)

Amount

Properties

  • currencyCode (string)
  • value (string)

Callback

Properties

  • id (string)
  • adapterId (string)
  • event
  • url (string)

CallbackEvent

Capability

Properties

  • name (string)
  • status (string)
  • limits (array) - Array of Limit

Cart

Properties

  • reference (string)
  • items (array) - Array of Item
  • discounts (array) - Array of Discount
  • total
  • attributes (object)

Properties

  • id (string)
  • checked (boolean)
  • text (string)
  • required (boolean)

CreateReferralDto

Properties

  • email (string)
  • returnUrl (string)

Customer

Properties

  • billing
  • shipping
  • type
  • attributes (object)

CustomerType

DeliveryDetails

Properties

  • carrier (string)
  • class (string)
  • product
  • pickupLocation

Discount

Properties

  • type
  • name (string)
  • code (string)
  • value
  • attributes (object)

DiscountType

Error

Properties

  • code (string)
    • Error code
    • Example: "cart-not-found"
  • message (string)
    • Detailed error information
    • Example: "Cart with id:{id} now found."

Hook

Properties

  • id (string)
  • adapterId (string)
  • subscribeTo (string)
  • target (string)
  • invoke (string)

Intent

Item

Properties

  • id (string)
  • reference (string)
  • name (string)
  • sku (string)
  • url (string)
  • imageUrl (string)
  • quantity (integer)
  • unit (string)
  • price
  • total
  • originalTotal
  • vatRate (number)
  • discounts (array) - Array of Discount
  • logistics
  • attributes (object)

Limit

Properties

  • type (string)

Properties

  • href (string)
  • rel (string)
  • method (string)

Logistics

Properties

  • weight (integer)
  • height (integer)
  • width (integer)
  • length (integer)

MerchantOnboardingStatus

Properties

  • merchantId (string)
  • trackingId (string)
  • products (array) - Array of PaypalProduct
  • capabilities (array) - Array of Capability
  • paymentsReceivable (boolean)
  • legalName (string)
  • primaryEmailConfirmed (boolean)
  • oauthIntegrations (array) - Array of OAuthIntegration
  • primaryCurrency (string)
  • country (string)

NorceOrder

Properties

  • id (string)
  • merchant (string)
  • channel (string)
  • reference (string)
  • created (string)
  • lastModified (string)
  • state
  • culture (string)
  • currency (string)
  • country (string)
  • cart
  • shippings (array) - Array of Shipping
  • payments (array) - Array of Payment
  • customer
  • consents (array) - Array of Consent
  • validations (array) - Array of Callback
  • hooks (array) - Array of Hook
  • notifications (array) - Array of Callback
  • total
  • attributes (object)

OAuthIntegration

Properties

  • integrationType (string)
  • integrationMethod (string)
  • oauthThirdParty (array) - Array of OAuthThirdParty

OAuthThirdParty

Properties

  • partnerClientId (string)
  • merchantClientId (string)
  • scopes (array)

OrderStatus

PatchOperation

Properties

  • op (string)
  • path (string)
  • value

Payment

Properties

  • id (string)
  • adapterId (string)
  • name (string)
  • merchant (string)
  • channel (string)
  • currency (string)
  • type
  • orderId (string)
  • amount (number)
  • upperLimitAmount (number)
  • state
  • reference (string)
  • attributes (object)
  • actions (array) - Array of PaymentAction
  • recurring

PaymentAction

Properties

  • id (string)
  • adapterId (string)
  • type (string)
  • url (string)

PaymentState

PaymentType

PaypalOrder

Properties

  • paymentId (string)
    • Norce Payment Id
  • reference (string)
    • PayPal Payment Reference ID
  • sdkUrl (string)
  • partnerAttributionId (string)
    • On the script tag, this value should go in the attribute data-partner-attribution-id.
  • sdkSettings
    • These properties should be added as query string parameters to the sdk url as kebab-case.

PaypalProduct

Properties

  • name (string)
  • vettingStatus (string)
  • status (string)

PaypalSdkSettings

Properties

  • clientId (string)
  • merchantId (string)
  • currency (string)
  • locale (string)
  • buyerCountry (string)
  • disableFunding (array)
  • enableFunding (array)
  • commit (boolean)
    • The commit status of the transaction. Determines whether to show a Pay Now or Continue button in the Checkout flow.
  • vault (boolean)
  • integrationDate (string)
  • intent

PaypalShippingAddressChangeRequest

Properties

  • shippingAddress

PaypalShippingAddressChangeResponse

Properties

  • success (boolean)
  • shippingAmount (number)
  • taxAmount (number)
  • totalAmount (number)

PaypalShippingOptionsChangeRequest

Properties

  • selectedShippingOption

PaypalWebhook

Properties

  • id (string)
  • create_time (string)
  • resource_type (string)
  • event_version (string)
  • event_type (string)
  • summary (string)
  • resource_version (string)
  • resource (object)
  • links (array) - Array of Link

PickupLocation

Properties

  • reference (string)
  • name (string)
  • address

PickupLocationAddress

Properties

  • streetAddress (string)
  • city (string)
  • postalCode (string)
  • country (string)

Price

Properties

  • includingVat (number)
  • excludingVat (number)

ProblemDetails

Properties

  • type (string)
  • title (string)
  • status (integer)
  • detail (string)
  • instance (string)

Product

Properties

  • reference (string)
  • name (string)

Recurring

Properties

  • token (string)
  • description (string)
  • attributes (object)

Shipping

Properties

  • id (string)
  • merchant (string)
  • channel (string)
  • state
  • reference (string)
  • tmsReference (string)
  • orderId (string)
  • adapterId (string)
  • name (string)
  • total
  • vatRate (number)
  • deliveryDetails
  • addons (array) - Array of Addon
  • attributes (object)

ShippingAddress

Properties

  • recipientName (string)
  • line1 (string)
  • line2 (string)
  • city (string)
  • state (string)
  • postalCode (string)
  • countryCode (string)

ShippingOption

Properties

  • id (string)
  • label (string)
  • selected (boolean)
  • type (string)
  • amount

ShippingState

State

Properties

  • currentStatus
  • transitions (array) - Array of Transition

Transition

Properties

  • status
  • timeStamp (string)