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. While this can be provided during initialization, it's common to use the `onBeforeProcessPayment` event to add or update details like the `invoiceId` just before payment processing. 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 and can be updated 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
`onLoad`	A function that is called when the PayPal button is successfully rendered.
`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 ideal place to create an order in your system and retrieve the `invoiceId` just before processing the payment. This is useful for Content Management Systems (CMS) that do not create an order ID until the user initiates payment. 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'),
    paymentData: {
        amount: 10.00,
        currency: 'GBP',
        invoiceId: 'INV-12345',
        // ... other payment data
    },
    token: 'YOUR_AUTH_TOKEN',
    events: {
        onLoad: () => {
            console.log('PayPal button loaded');
        },
        onClick: () => {
            console.log('PayPal button clicked');
        },
        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.

7. Advanced Usage

Dynamically Updating Payment Data

The onBeforeProcessPayment event is the ideal place to finalize payment details just before the transaction is processed. This is particularly useful for creating an order in your backend to get an invoiceId, or for fetching a fresh authentication token right before payment. This function must return a promise that resolves with the paymentData and token.

const params = {
    terminalId: 'YOUR_TERMINAL_ID',
    containerElement: document.getElementById('paypal-button-container'),
    events: {
        onBeforeProcessPayment: () => {
            // This is a great place to create an order in your backend
            // and get an invoiceId before processing the payment.
            return yourApi.createOrder().then(order => {
                resolve({
                    paymentData: {
                        amount: order.amount,
                        currency: order.currency,
                        invoiceId: order.id,
                        // ... other payment data
                    },
                    token: 'YOUR_AUTH_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​

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

7. Advanced Usage

Dynamically Updating Payment Data

Customizing the PayPal Button