Skip to main content

​
Before you begin

This guide assumes that you know how to

​
Accept payments with PayPal

​
Prepare the client session

PayPal requires the following data to process a payment successfully. Pass the following data in the client session, or in the payment request (for manual payment creation).
Parameter NameRequiredDescription
currencyCode✓3-letter currency code in ISO 4217 format, e.g. USD for US dollars
order
↳ lineItems		✓Details of the line items of the order
order
↳ countryCode		✓The country code of the user is required for PayPal.
metadata
↳ paypal_custom_id		Primer’s direct integration to PayPal enables you send a custom ID to paypal to link your orders to a specific custom ID.
metadata
↳ paypal_invoice_id		Primer’s direct integration to PayPal enables you send a Invoice ID to paypal to link your orders to a specific invoice ID.
metadata
↳ paypal_client_metadata_id		✓Required field if the Billing Agreement is being created.

​
Prepare the SDK for payments

  • Web
  • iOS
  • Android
  • React Native

​
Pre-requisites

If your website uses Content Security Policy, make sure to add the following rules:
PolicyOrigin
frame-srcc.paypal.com
child-srcc.paypal.com
script-srcc.paypal.com

​
Show Universal Checkout

PayPal is automatically presented to the customer when calling Primer.showUniversalCheckout.
Typescript

try {
  await Primer.showUniversalCheckout(clientToken, {
    container: '#checkout-container',
    options,
    onCheckoutComplete({ payment }) {
      console.log('Checkout complete.', payment)
    },
  })
} catch (e) {
  // handle error
}

​
Customization

Check the Customization Guide to learn how to customize payment method buttons.Additionally, you can style the PayPal button by passing the following options:
Typescript
const options = {
    /* Other options... */
    paypal: {
        buttonColor: 'gold', // 'gold' (default) | 'blue' | 'silver' | 'white' | 'black'
        buttonShape: 'pill', // 'pill' | 'rect'
        buttonSize: 'small', // 'small' | 'medium' | 'large' | 'responsive'
        buttonHeight: 50,
        buttonLabel: 'paypal', // 'paypal' (default) | 'checkout' | 'credit' | 'pay' | 'buynow' | 'installment'
        buttonTagline: false,     
    }
}

​
Limitations

The button provided by PayPal has a maximum width of 750px. This value is hardcoded by PayPal and cannot be updated. We encourage you to limit the width of the checkout to 750px to have consistent payment method buttons.

​
Troubleshooting

If the PayPal button fails to appear, check that a valid countryCode has been provided in the client session.If PayPal fails to render when the button is clicked, open your Developer Inspector - PayPal usually prints an error there.

​
Vaulting

Vaulting PayPal requires the Billing Agreement API to be activated on your account. Get in touch with your account manager at PayPal to activate this feature.In order to be approved by PayPal for Billing Agreements, you may be required to collect device data using their Fraudnet/Magnes library and pass a user session identifier to PayPal during the transaction. This can be done by passing this as metadata.paypal_client_metadata_id in the Primer Client Session/Payment API.In order to vault PayPal accounts, pass the following data in the Client Session:
Parameter NameRequiredDescription
customerId✓A unique identifier for your customer

​
Prepare the SDK for vaulting

  • Web
  • iOS
  • Android
  • React Native
When showing drop-in checkout, set the option paymentFlow to PREFER_VAULT.
Typescript
    Primer.showUniversalCheckout(clientToken, {
        // Other options
        paypal: {
            paymentFlow: "PREFER_VAULT"
        }
    });

​
Test

When testing PayPal in your Primer Sandbox, make sure to use a PayPal sandbox account, not your own PayPal account. Go to PayPal’s Developer Dashboard to manage your sandbox accounts.

​
Go live

You don’t need to do anything particular to go live! Just make sure to use the Production credentials!