VeryPay SDK Development Integration Guide

Powerful tool for integrating VeryPay payment functionality into your applications

The default JS SDK code snippet blocks page rendering:

<script src="https://www.verypay.ch/sdk/js?client-id=test"></script>
<script>
  verypay.renderButton({
	  selector: "body", // replace body to your element
	  clientId: "CLIENT_ID", // .e.g: VeryPay
	  env: "TARGET_ENV", // test, uat, demo, production
	  merchantId: "MERCHANT_ID",// .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
	  initialData: paymentData,
	  onPaymentCompleted(transaction) {
	    // Callback when payment is completed
	  },
	  // ... other options and callbacks
	});
</script>

The VeryPay SDK is a powerful tool for integrating VeryPay payment functionality into your applications.

This guide will walk you through the steps to integrate the VeryPay SDK into your project, and provide examples of how to use the renderButton function to enable payments.

Table of Contents

• Installation
• Usage
  • JavaScript
  • HTML
• Options
  • Detail for initialData object param
• Callbacks
• Example
  • React Code snippet
  • HTML Example
• License

Installation

You can install the VeryPay SDK via packages:

# npm
npm install @verysell-group/verypay-sdk
# yarn
yarn add @verysell-group/verypay-sdk
# pnpm
pnpm add @verysell-group/verypay-sdk

Usage

JavaScript

To use the VeryPay SDK in a JavaScript application, you can import it as follows:

import { renderButton } from "@verysell-group/verypay-sdk";

// Initialize the VeryPay button
renderButton({
  selector: "#verypay-button",
  clientId: "CLIENT_ID", // .e.g: VeryPay
  env: "TARGET_ENV", // test, uat, demo, production
  merchantId: "MERCHANT_ID", // .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
  initialData: paymentData,
  onPaymentCompleted(transaction) {
    // Callback when payment is completed
  },
  // ... other options and callbacks
});

HTML

If you prefer to include the VeryPay SDK in your HTML file, you can use the following script tag:

<script src="https://verypay-demo.verypay.ch/sdk/verypay-checkout.js"></script>

You can then use the global verypay object to render the button:

verypay.renderButton({
  selector: "#verypay-button",
  clientId: "CLIENT_ID", // .e.g: VeryPay
  env: "TARGET_ENV", // test, uat, demo, production
  merchantId: "MERCHANT_ID", // .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
  initialData: paymentData,
  onPaymentCompleted(transaction) {
    // Callback when payment is completed
  },
  // ... other options and callbacks
});

Options

Here are the available options when calling renderButton:

• selector (string): The CSS selector for the element where the VeryPay button should be rendered.
• clientId (string): Your VeryPay client ID.
• baseURL (string): The base URL for VeryPay API requests.
• merchantId (string): Your merchant ID.
• initialData (object): Initial payment data.
• onPaymentCompleted (function): Callback function when payment is completed.
• onPaymentFailed (function): Callback function when payment fails.
• onAddressesSelected (function): Callback function when addresses are selected.
• onAuthenticationSuccess (function): Callback function when authentication is successful.
• onShippingSelected (function): Callback function when shipping is selected.

Detail for initialData object param

type InitialData = {
    clientCartId: string;
    orderDetails: {
        items: {
            id: string;
            quantity: number;
            name: string;
            sku: string;
            price: number;
            amount: number;
        }[];
        tax: number;
        shippingFee: number;
        totalPrice: number;
        currency: string;
    };
    defaultShippingOption: string;
    shippingOptions: {
        id: string;
        amount: number;
        name: string;
    }[]
}

• clientCartId (string): A unique identifier for the client's cart. This identifier helps link the cart to the client's session or profile.
• orderDetails (object): An object containing information about the client's order.
  • items (array of objects): An array of items in the client's order. Each item object includes the following properties:
    • id (string): A unique identifier for the item.
    • quantity (number): The quantity of this item in the order.
    • name (string): The name or description of the item.
    • sku (string): The Stock Keeping Unit (SKU) identifier for the item.
    • price (number): The individual price of one unit of this item.
    • amount (number): The total amount for this item (quantity multiplied by price).
  • tax (number): The total tax amount for the order.
  • shippingFee (number): The shipping fee for the order.
  • totalPrice (number): The total price of the order, including the subtotal, tax, and shipping fees.
  • currency (string): The currency in which the prices are specified, e.g., "USD" for US Dollars.
• defaultShippingOption (string): The identifier for the default or selected shipping option for the order. This should match one of the id values in the shippingOptions array.
• shippingOptions (array of objects): An array of available shipping options for the order. Each shipping option object includes the following properties:
  • id (string): A unique identifier for the shipping option.
  • amount (number): The cost of this shipping option.
  • name (string): The name or description of the shipping option.

These parameters collectively provide detailed information about the client's shopping cart and order, allowing the VeryPay SDK to calculate the total amount, including tax and shipping fees, for the order.

Callbacks

Callbacks are functions that you can define to handle various events during the payment process. These are passed as options when calling renderButton. See the Options section for details on which callbacks are available.

Example

Here is an example of how to use renderButton:

renderButton({
  selector: "#verypay-button",
  clientId: "CLIENT_ID", // .e.g: VeryPay
  env: "TARGET_ENV", // test, uat, demo, production
  merchantId: "MERCHANT_ID", // .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
  initialData: paymentData,
  onPaymentCompleted(transaction) {
    // Callback when payment is completed
  },
  onPaymentFailed() {
    // Callback when payment failed
  },
  onAddressesSelected(addresses) {
    // Handle selected addresses
  },
  onAuthenticationSuccess() {
    // Handle when login successfull
  },
  onShippingSelected(shippingOptionId) {
    // Handle selected shipping option
    // ...
  },
});

React Code snippet example

import { useEffect } from "react";
import { renderButton } from "@verysell-group/verypay-sdk";

export const PaymentButton = () => {
  useEffect(() => {
    renderButton({
      selector: "#verypay-buttons",
      clientId: "CLIENT_ID", // .e.g: VeryPay
      env: "TARGET_ENV", // test, uat, demo, production
      merchantId: "MERCHANT_ID", // .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
      // ...pass the callback function here
    });
  }, []);

  return <div id="verypay-button" />;
};

HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>VeryPay SDK - HTML Example</title>
  <script src="https://verypay-demo.verypay.ch/sdk/verypay-checkout.js"></script>
</head>
<body>
  <div id="verypay-buttons"></div>

  <script type="module">
    verypay.renderButton({
      selector: "#verypay-buttons",
		  clientId: "CLIENT_ID", // .e.g: VeryPay
		  env: "TARGET_ENV", // test, uat, demo, production
		  merchantId: "MERCHANT_ID",// .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
      // ...pass the callback function here
    });
  </script>
</body>
</html>

Using a CDN

The verypay-sdk script is also available on the unpkg CDN. Here's an example:

<!doctype html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/@verysell-group/verypay-sdk@latest/dist/verypay-sdk.iife.js"></script>
  </head>
  <body>
    <div id="verypay-buttons"></div>
    <script>
      verypay.renderButton({
	      selector: "#verypay-buttons",
			  clientId: "CLIENT_ID", // .e.g: VeryPay
			  env: "TARGET_ENV", // test, uat, demo, production
			  merchantId: "MERCHANT_ID",// .e.g: b2e56b86-c599-4432-8c81-bf5f15fcd267
	      // ...pass the callback function here
	    });
    </script>
  </body>
</html>

TypeScript Support

This package includes TypeScript type definitions for the Verypay JS SDK. This includes types for the window.verypay namespace. We support projects using TypeScript versions >= 3.8.

Releasing

Run npm run release to publish a new release. The version number is determined by the git commits which follow conventional commits spec.

License

Verysell Group - VeryPay