PayPal Checkout Utility Methods

Important

These utility methods are compatible with PayPal SDK v6. For previous PayPal SDK versions, see the previous utility method documentation.

getHandleApproveOrder

Returns a callback to pass to the PayPalButtons for onApprove.

Parameters

Parameter

Type

Required?

Description

authState

AuthState

✅

Information about the authentication state of the customer.

cartId

string

✅

The cart ID for this request.

getPayPalOrder

(cartId: string, paypalOrderId: string) ⇒ Promise<OrderResponseBodyWithModules | undefined>

✅

The callback to fetch the PayPal Order.

Response

Field

Type

Description

handleApproveOrder

HandleApproveOrder

The callback function to pass into PayPalButtons' onApprove parameter. Populates the paymentGatewayProperties for Payment creation in PaymentTransactionServices.

HandleApproveOrder

Parameter

Type

Required?

Description

handleApproveOrder

Function

✅

The callback function to pass into PayPalButtons' onApprove parameter. Returns address, attributes, and paymentGatewayProperties. Compatible with PayPal SDK v6, and expects to receive OnApproveDataOneTimePayments data.

Example Usage

const handleApproveOrder = getHandleApproveOrder({ authState, cartId, getPayPalOrder });
const onSubmit = useCallback(
  async (data) => {
    const { attributes, paymentGatewayProperties } = await handleApproveOrder(
      data
    );

    const paymentRequest = {
        ...
        paymentGatewayProperties,
        attributes,
    } as PaymentRequest;

    // add payment with paymentRequest payload
})

getHandleCreateOrder

Returns a callback to pass to the PayPalButtons for createOrder.

Parameters

Parameter

Type

Required?

Description

config

CreateOrderConfig

✅

The configuration needed to create the order.

CreateOrderConfig

Name Type Required? Description

Name	Type	Required?	Description
`cartState`	`CartState`	✅	Important information about the state of the cart.
`createPayPalOrder`	`(cartId: string, request: CreateOrderRequestBodyWithModules) ⇒ Promise<{ orderId: string }>`	✅	The callback to create the PayPal Order.
`userAction`	`enum`	❌	The user action to be specified on the experience context. See PayPal’s experience context definition for more details.
`shippingCallbackUrl`	`string`	❌	The URL that PayPal should call for server-side shipping callback APIs, if any. See PayPal’s experience context definition for more details.
`shippingPreference`	`enum`	✅	The shipping preference to be specified on the experience context. See PayPal’s experience context definition for more details.
`intent`	`PayPalPaymentIntent`	❌	Intent of payment transaction, either to capture immediately or authorize the order.
`purchaseUnitConfig`	`PurchaseUnitConfig`	❌	Configuration to determine what information to populate on the purchase unit.
`returnUrl`	`string`	❌	The return URL, if any, to send to PayPal on the experience context. See PayPal’s experience context definition for more details.
`cancelUrl`	`string`	❌	The cancel URL, if any, to send to PayPal on the experience context. See PayPal’s experience context definition for more details.
`setError`	`Function`	✅	Used to track the error state, e.g. `setError: (error: unknown) ⇒ void;`
`setFundingSource`	`Function`	✅	Used to track the funding source, e.g. `setFundingSource: (fundingSource: string) ⇒ void;`

cartState

CartState

✅

Important information about the state of the cart.

createPayPalOrder

(cartId: string, request: CreateOrderRequestBodyWithModules) ⇒ Promise<{ orderId: string }>

✅

The callback to create the PayPal Order.

userAction

enum

❌

The user action to be specified on the experience context. See PayPal’s experience context definition for more details.

shippingCallbackUrl

string

❌

The URL that PayPal should call for server-side shipping callback APIs, if any. See PayPal’s experience context definition for more details.

shippingPreference

enum

✅

The shipping preference to be specified on the experience context. See PayPal’s experience context definition for more details.

intent

PayPalPaymentIntent

❌

Intent of payment transaction, either to capture immediately or authorize the order.

purchaseUnitConfig

PurchaseUnitConfig

❌

Configuration to determine what information to populate on the purchase unit.

returnUrl

string

❌

The return URL, if any, to send to PayPal on the experience context. See PayPal’s experience context definition for more details.

cancelUrl

string

❌

The cancel URL, if any, to send to PayPal on the experience context. See PayPal’s experience context definition for more details.

setError

Function

✅

Used to track the error state, e.g. setError: (error: unknown) ⇒ void;

setFundingSource

Function

✅

Used to track the funding source, e.g. setFundingSource: (fundingSource: string) ⇒ void;

PurchaseUnitConfig

Name Type Required? Description

Name	Type	Required?	Description
`includeItems`	`boolean`	❌	If true, includes the cart items in the Purchase Unit.
`includeShipping`	`boolean`	❌	If true, includes the shipping information in the Purchase Unit.

includeItems

boolean

❌

If true, includes the cart items in the Purchase Unit.

includeShipping

boolean

❌

If true, includes the shipping information in the Purchase Unit.

Response

Field

Type

Description

createOrder

createOrder callback function

The callback function to pass into PayPalButtons' createOrder parameter.

Example Usage

const createOrder = getHandleCreateOrder({
    cartState,
    createPayPalOrder,
    userAction,
    shippingCallbackUrl,
    purchaseUnitConfig: {
      includeItems: true,
      includeShipping: true,
    },
    shippingPreference,
    setError,
    setFundingSource,
});

getPaymentReviewDisplay

Returns the email attribute associated with the PayPal account from the PaymentSummary.

Parameters

Parameter

Type

Required?

Description

payment

Payment Summary

✅

The payment summary to display for review.

Response

Field

Type

Description

paymentDisplay

string

The email attribute from the payment summary associated with the PayPal account.

Example Usage

const paymentDisplay = getPaymentReviewDisplay(payment);