Skip to main content

Integration

Initial Setup​

Step 1: Add the Alipay+ Script​

Include the following script tag in the <head> section of your HTML page:

TEST:

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

LIVE:

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

Step 2: Create a DOM Element​

Create a container where the Alipay+ button will be rendered:

<div id='alipay-plus-btn-container'></div>

Event Handlers for Alipay+​

Step 3: Handling the onClick Event​

The onClick event is triggered when the Alipay+ button is clicked. You can use this handler to manage the click event:

function onClick() {
    console.log('Alipay+ button has been clicked');
    // Optional: return custom timeout
    // return { paymentTimeoutInSeconds: 120 };
}

Step 4: Handling Errors with onError​

The onError event handles errors that occur during the Alipay+ process. It is essential to handle these errors gracefully to ensure a good user experience:

function onError(error) {
    console.log('Error occurred:', error);
    // You can access error.code, error.message, and error.additionalInfo
}

Step 5: Handling the onCancel Event​

The onCancel event is triggered when a user cancels the Alipay+ transaction. Implement this callback to reset the checkout process or notify the user:**

function onCancel(event) {
    console.log('Payment was cancelled:', event);
    // Reset the checkout state
}

Step 6: Handling the onPaymentSuccess Event​

The onPaymentSuccess event is triggered when a payment is successfully processed. Use this handler to finalize the transaction and retrieve customer details:

function onPaymentSuccess(result) {
    console.log('Payment has successfully been processed', result);

    // Implement further actions such as redirecting to a success page or storing the payment details
}

Step 7: Handling the onBeforeProcessPayment Event (Optional)​

The onBeforeProcessPayment event is an asynchronous event handler that is called just before the payment is processed. You can return a promise that resolves to an object containing payment data or a token. This is useful for providing or updating data dynamically.

async function onBeforeProcessPayment() {
    // Perform any necessary actions, like making an API call to your backend
    const data = await fetch('/api/get-payment-data');
    const result = await data.json();

    return {
        paymentData: result.paymentData,
        token: result.token,
        paymentTimeoutInSeconds: 120 // Optional: custom timeout for the QR code
    };
}

Step 8: Creating a Combined Events Object​

You can create an events object that consolidates all event handlers for easier management:

const events = {
    onClick,
    onError,
    onPaymentSuccess,
    onCancel,
    onBeforeProcessPayment
};

Button Initialization​

Step 9: Configure paymentData​

Before initializing the Alipay+ button, you need to configure the paymentData object, which contains the details of the payment transaction, such as the currency, amount, and customer details.

const paymentData = {
    currency: 'GBP',  // The currency of the transaction
    description: 'Shoes',  // A brief description of the items or services being purchased
    paymentSettings: {
        terminalId: 'YOUR_TERMINAL_ID',  // Your terminal ID
        returnUrl: 'https://example.com/success.html',  // URL to redirect upon successful payment
        failureReturnUrl: 'https://example.com/failure.html',  // URL to redirect upon payment failure
        callbackUrl: 'https://example.com/callback',  // URL for server-to-server callbacks
        failureCallbackUrl: 'https://example.com/failure-callback'  // URL for handling callback failures
    },
    customerDetails: {
        accountDetails: {
            accountId: 'uuid000001'  // Unique identifier for the customer account
        },
        billingAddress: {
            firstName: 'John',
            lastName: 'Doe',
            addressLine1: 'Fulham Rd',
            postalCode: 'SW6 1HS',
            city: 'London',
            country: 'GB'
        },
        deliveryDetails: {
            deliveryAddress: {
                firstName: 'John',
                lastName: 'Doe',
                addressLine1: 'Fulham Rd',
                addressLine2: 'Fulham',
                postalCode: 'SW6 1HS',
                city: 'London',
                phone: '44-07123456789',
                country: 'GB'
            }
        },
        email: 'example@email.com',
        mobilePhone: '44-07123456789'
    },
    orderLines: [
        {
            name: 'Running shoe',  // Item name
            quantity: 1,  // Quantity of the item
            unitPrice: 24,  // Price per unit
            taxRate: 20,  // Tax rate applied
            totalAmount: 24,  // Total amount for this item
            totalTaxAmount: 4,  // Total tax amount for this item
            imageUrl: 'https://www.example.com/logo.png',  // URL of the item's image
            productUrl: 'https://www.example.com/AD6654412.html'  // URL to the product page
        }
    ],
    deliveryType: 'service',  // Type of delivery (e.g., service, physical)
    invoiceId: 'YOUR_REFERENCE',  // Unique identifier for the transaction invoice
    amount: 24  // Total transaction amount
};

Step 10: Initialize the Button​

To initialize the Alipay+ button and configure it for processing transactions, use the init method.

[Deprecation Notice]

The create method is deprecated and will be removed in future versions. Please migrate to the init method.

window.DNAPayments.AlipayPlusComponent.init({
    containerElement: document.getElementById('alipay-plus-btn-container'),  // The container element where the button will be rendered
    events: events,  // The events object containing all your event handlers
    paymentData: paymentData,  // Your configured payment data
    token: 'YOUR_ACCESS_TOKEN',  // Your access token
    paymentTimeoutInSeconds: 60 // Optional: Timeout for the QR code display
});
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 in the Authentication Guide.

info

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

This integration guide provides all necessary steps to integrate the Alipay+ button into your website, including loading the script, setting up event handlers, configuring payment data, and initializing the button. Make sure to replace placeholders like YOUR_ACCESS_TOKEN, YOUR_TERMINAL_ID, and YOUR_INVOICE_ID with your actual data.