PayPal Component Integration Guide

This guide provides detailed instructions for merchants and developers to integrate the DNA Payments PayPal component into a web page.

1. Introduction

The DNA Payments PayPal component provides a seamless way to integrate PayPal payments into your website. It handles the rendering of the PayPal button, manages the payment flow, and communicates with the DNA Payments API to process transactions.

2. Setup and Installation

To use the PayPal component, you need to include the bundled JavaScript file in your HTML page. The component is bundled into a single file named paypal-component.js.

HTML Setup

Include the paypal-component.js script in your HTML file. TEST:

<script src='https://test-pay.dnapayments.com/components/paypal/paypal-component.js'></script>

LIVE:

<script src='https://pay.dnapayments.com/components/paypal/paypal-component.js'></script>

Create a container element (e.g., a div) where the PayPal button will be rendered.

<!DOCTYPE html>
<html>
<head>
    <title>PayPal Integration</title>
</head>
<body>

    <!-- Container for the PayPal button -->
    <div id="paypal-button-container"></div>

    <!-- Include the PayPal component script -->
    <script src="https://test-pay.dnapayments.com/components/paypal/paypal-component.js"></script>

    <script>
        // Your integration script goes here
    </script>

</body>
</html>

3. Initialization

The PayPal component is initialized by calling the DNAPayments.PayPalComponent.init() function. This function returns a promise that resolves with an instance of the PayPal component.

`init(params)`

params: An object containing the configuration for the PayPal component.

Example

const params = {
    terminalId: 'YOUR_TERMINAL_ID',
    containerElement: document.getElementById('paypal-button-container'),
    // ... other configuration options
};

DNAPayments.PayPalComponent.init(params)
    .then(payPalComponent => {
        console.log('PayPal component initialized', payPalComponent);
    })
    .catch(error => {
        console.error('Failed to initialize PayPal component', error);
    });

4. Configuration Options

The init function accepts a PayPalParams object with the following properties:

Parameter	Type	Required	Description
`terminalId`	`string`	Yes	Your unique terminal ID provided by DNA Payments. This is used to fetch the specific configuration for your terminal, including your PayPal client ID and other settings.
`containerElement`	`HTMLElement`	Yes	The HTML element where the PayPal button will be rendered. This should be an empty `div` or a similar container element.
`paymentData`	`object`	No	An object containing the payment details. This can be provided during initialization or later via the `onBeforeProcessPayment` event. See the PaymentRequest Object section for more details.
`token`	`string`	No	The authentication token for creating orders. This is required for making API calls to the DNA Payments backend. It can be provided during initialization or later via the `onBeforeProcessPayment` event.
`language`	`string`	No	The language for the PayPal button and the payment flow. It should be a valid language string, e.g., `'en'`, `'de'`, `'es'`, `'pt'`, `'is'`. Defaults to `'en'`.
`environment`	`string`	No	The environment to use. Can be `'sandbox'` for testing or `'production'` for live transactions. Defaults to `'production'` when using the production script and `'sandbox'` when using the test script.
`buttonStyle`	`object`	No	An object to customize the appearance of the PayPal button. See the PayPal documentation for available options.
`events`	`object`	No	An object with callback functions for different events during the payment process. See the Events section for details.

5. Events

You can provide callback functions to handle different events during the payment process. The events object in the PayPalParams allows you to listen for these events and execute custom logic.

Event	Description
`onClick`	A function that is called when the PayPal button is clicked. The component will show a loader and disable the button to prevent multiple clicks.
`onBeforeProcessPayment`	An asynchronous function that is called after `onClick` and before the payment is processed. This is the place to provide or update the `paymentData` and `token`. This function must return a promise that resolves with an object containing `paymentData` and `token`.
`onPaymentSuccess`	A function that is called when the payment is successfully approved. It receives the response from the server as an argument.
`onCancel`	A function that is called when the user cancels the payment.
`onError`	A function that is called when an error occurs. It receives an error object as an argument.

Example

const params = {
    terminalId: 'YOUR_TERMINAL_ID',
    containerElement: document.getElementById('paypal-button-container'),
    events: {
        onClick: () => {
            console.log('PayPal button clicked');
        },
        onBeforeProcessPayment: () => {
            console.log('Processing payment...');
            // Return a promise to provide/update paymentData and token
            return new Promise(resolve => {
                resolve({
                    paymentData: {
                        amount: 10.00,
                        currency: 'GBP',
                        invoiceId: 'INV-12345',
                        // ... other payment data
                    },
                    token: 'YOUR_AUTH_TOKEN'
                });
            });
        },
        onPaymentSuccess: (response) => {
            console.log('Payment successful', response);
        },
        onCancel: () => {
            console.log('Payment cancelled');
        },
        onError: (error) => {
            console.error('An error occurred', error);
        }
    }
};

DNAPayments.PayPalComponent.init(params);

6. Troubleshooting

Common Issues

PayPal button not rendering:
- Ensure that the containerElement exists in the DOM before initializing the component.
- Check the browser console for any other error messages.
- Verify that the terminalId is correct and the PayPal configuration is active in your DNA Payments account.
"Failed to fetch terminal configuration" error:
- This error indicates that the component could not retrieve the configuration associated with the provided terminalId.
- Check your network connection and ensure that the DNA Payments API is accessible.
- Verify that the terminalId is correct.
"PayPal client ID not found" error:
- This error means that the PayPal client ID is missing from the terminal configuration.
- Contact DNA Payments support to ensure that your account is correctly configured for PayPal payments.

Known Limitations

The component does not currently support all the features of the PayPal JavaScript SDK.
The component is designed to be used in a browser environment and is not suitable for server-side rendering.

7. Advanced Usage

Dynamically Updating Payment Data

You can dynamically update the payment data when the user clicks the PayPal button by using the onBeforeProcessPayment event. This is useful when the payment amount or other details are not known until the user interacts with the page.

const params = {
    terminalId: 'YOUR_TERMINAL_ID',
    containerElement: document.getElementById('paypal-button-container'),
    events: {
        onBeforeProcessPayment: () => {
            return new Promise(resolve => {
                // Fetch the latest payment data from your server
                const paymentData = {
                    amount: document.getElementById('amount-input').value,
                    currency: 'GBP',
                    // ...
                };
                const token = 'YOUR_AUTH_TOKEN';
                resolve({ paymentData, token });
            });
        },
        // ... other events
    }
};

DNAPayments.PayPalComponent.init(params);

Customizing the PayPal Button

You can customize the appearance of the PayPal button by providing a buttonStyle object in the configuration.

const params = {
    terminalId: 'YOUR_TERMINAL_ID',
    containerElement: document.getElementById('paypal-button-container'),
    buttonStyle: {
        layout: 'vertical',
        color:  'gold',
        shape:  'rect',
        label:  'paypal'
    },
    // ... other configuration
};

DNAPayments.PayPalComponent.init(params);

For more information on the available style options, please refer to the PayPal documentation.

info

The paymentData and token can be passed directly in the params object during initialization if they are known at page load. However, for dynamic amounts or to ensure the latest auth token is used, we recommend providing them from the onBeforeProcessPayment handler as shown in the example.

info

The access token returned from the API is an object that includes several fields such as access_token, expires_in, token_type, and others. Only the access_token field should be passed during button initialization. For more details on how to obtain the access token, follow the instructions outlined here.

info

When obtaining the access token, make sure to pass the following scopes to ensure proper initialization of the button: payment integration_seamless.

PayPal Component Integration Guide

1. Introduction​

2. Setup and Installation​

HTML Setup​

3. Initialization​

init(params)​

Example​

4. Configuration Options​

5. Events​

Example​

6. Troubleshooting​

Common Issues​

Known Limitations​

7. Advanced Usage​

Dynamically Updating Payment Data​

Customizing the PayPal Button​

1. Introduction

2. Setup and Installation

HTML Setup

3. Initialization

`init(params)`

Example

4. Configuration Options

5. Events

Example

6. Troubleshooting

Common Issues

Known Limitations

7. Advanced Usage

Dynamically Updating Payment Data

Customizing the PayPal Button