XceedAdyen payments

JS library to provide functionalities and interaction with the Adyen checkout-service

This npm package provides functionalities and interaction with the Payment Micro Service. It’s meant to be used in all the web platforms, currently including the Xceed Widget and the B2C xceed.me.

The package allows a platform to pay through different methods:

• Credit Card payments
• 3DSecure1 security payments
• 3DSecure2 security payments
• Payments with ticket holders information
• No payments bookings

It automatically takes care of the redirects and tickets generation, over the errors handling and the buyer information.

Table of contents

• Requirements
• Installation
• Usage and code sample
  • Code
  • Steps
• Api
  • XceedClient
    • XceedClient()
    • Xceed.prototype.init
    • Xceed.prototype.createCheckout
    • Xceed.prototype.createDropin
    • Xceed.fetchOriginKey
    • Xceed.fetchPaymentMethods
    • Xceed.addScripts
    • Xceed.createBooking
    • Xceed.generateTicket
    • Xceed.pay
    • Xceed.submitAdditionalDetails
  • XceedDropin
    • bookingData
    • payment
    • formFields/ticketHolderFields
    • Implementation details
• Development
• Contributors
• License

Requirements

• Node 8 or later.
• Npm 5 or later.

Installation

npm

To install the library using npm, type on your terminal:

npm install @xceed/adyenjs

yarn

To install the library using yarn, type on your terminal:

yarn add @xceed/adyenjs

bitbucket

Until the library won't be available on the npm registry, install it from the bitbucket repo, type on your terminal:

npm install git+ssh://[email protected]/Xceed/adyenjs-payments.git#develop

Usage and code sample

Since we want to abstract from the checkout flow the submission action, it's necessary to proceed in steps to generate the dropin:

1. Create an instance of the XceedClient.
2. Initialize the instance using the XceedClient.prototype.init method and passing the necessary options.
3. Using the XceedClient instance, create a new checkout service with th XceedClient.prototype.createCheckout method.
4. When the checkout service has been created, you can finally generate a new dropin with the XceedClient.prototype.createDropin method.

Now the we have all the needed elements, we can add to our component the XceedDropin in order to render the form.

Let's check an example and later we'll comment it.

Code

import React, { useState, useEffect } from 'react';
import { XceedClient, XceedDropin } from '@xceed/adyenjs';

function MyCheckoutComponent() {
  // ======
  // STEP 1
  // ======
  const [dropin, setDropin] = useState(null);
  const [isDisabled, setIsDisabled] = useState(true);

  // ======
  // STEP 2
  // ======
  const bookingData = {
    rsvp: 216965,
    prid: 11315,
    source: 'widget',
    numTickets: 1,
    price: 20,
    fee: 1.85,
    widgetId: 3,
    eventId: 74889,
    venueName: 'Pacha',
  };

  const ticketHolderFields = [
    { name: 'firstName', displayName: 'First Name', dataType: 'text', required: true },
    { name: 'lastName', displayName: 'Last Name', dataType: 'text', required: true },
    { name: 'phone', displayName: 'Phone', dataType: 'numeric', required: false },
  ];

  // ======
  // STEP 3
  // ======
  useEffect(() => {
    (async () => {
      const xceedClient = new XceedClient();
      await xceedClient.init({ country: 'ES', currency: 'EUR', amount: 10 });
      const checkout = xceedClient.createCheckout({ locale: 'es-ES' });
      const newDropin = xceedClient.createDropin(checkout, { enableStoreDetails: false });
      setDropin(newDropin);
    })();
  }, []);

  // ======
  // STEP 4
  // ======
  function onSuccess(paymentResult) {
    console.log('payment result', paymentResult);
  }

  function onFailure(error) {
    console.log('payment error', error);
  }

  function onPending() {
    console.log('Paying.....');

    return function() {
      console.log('End waiting time!');
    };
  }

  // ======
  // STEP 5
  // ======
  return dropin ? (
    <>
      <XceedDropin
        dropin={dropin}
        setDropin={setDropin}
        bookingData={bookingData}
        payment={{ amount: 10, country: 'ES', currency: 'EUR', storePaymentMethod: false }}
        ticketHolderFields={ticketHolderFields}
        disabler={setIsDisabled}
        onSuccess={onSuccess}
        onFailure={onFailure}
        onPending={onPending}
        lang="es"
      />
      <button disabled={isDisabled} onClick={dropin.submit}>
        Submit now
      </button>
    </>
  ) : null;
}

Steps

1. Inside our MyCheckoutComponent, we need to declare two states:

   • dropin: it will hold the dropin instance
   • isDisabled: it will hold the status to disable/enable our submit button, it should default to true to get our button disabled in the beginning.

2. Declare the informations about your booking:

   • rsvp: the selected rsvp id,
   • prid: the promoter id,
   • source: the source platform for this purchase (web|widget),
   • numTickets: bought tickets number
   • price: price for ticket
   • fee: fee for ticket
   • widgetId: id of the club widget (only if from widget source)
   • eventId: id for event rsvp
   • venueName: name of the event venue

   Also, if they are passed, you need to pass the array of ticketHolderFields.

3. In this step, we run an effect on mount of our component to:

   • Create the xceedClient instance with XceedClient constructor.
   • Await for the async operation of initialisation. This operation takes care of fetching the public key for the service, the available payments methods, and the necessary scripts to create a new checkout. It take options as country and currency, over others available in the Api section.
   • Create a new checkout using the .createCheckout method. It returns a new checkout instance, and accept an object with the locale option for the form internationalization purpose.
   • With the .createDropin method, we create our new dropin, passing the checkout instance as first argument (it's necessary for the dropin creation), and an optional object of options.
   • Finally, we set the dropin state to the newly created dropin instance, ready to be passed to the XceedDropin component.

4. The XceedDropin component accept many props, some of them related to events to handle successful payments, pending operations, or even failed payments. It's up to the developer decide if pass or not these optional events to handle the interactions with the XceedDropin component. See more about events on the Api section.

5. In this last step, we are ready to render the component and the external submit button. XceedDropin need at least some required props to properly work:

   • dropin: the dropin state that hold the dropin instance created with the effect on mount.
   • setDropin: the dropin setter, essential for the component to handle internal logic.
   • bookingData: the previously created object with the booking information.
   • payment: the payment object contains information about the total amount to pay, the currency and other options. See more in the Api section.
   • disabler: the isDisabled state setter to internally handle if the form is ready to be submitted.

   About the submit action, any button or element able to trigger an event can use the method dropin.submit coming directly from the dropin instance and updated thanks to internal logic.

   Also, is possible to use the isDisabled state to keep disabled the submit trigger until the form is not validate.

Api

XceedClient

• XceedClient()

  The XceedClient constructor, it creates an instance to create checkout services and dropins.

• Xceed.prototype.init([options])

  This async method initialize the instance of XceedClient and create all the necessary resources to create checkout services.

  It takes optional setting passed through an object:

  | Option | Description | Type | Required | Default | | ---------------- | ------------------------------------------------------------------------------------------------------- | ------ | -------- | ------- | | amount | Represents the amount to pay for the current payment. | number | true | 20 | | channel | The channel used to fetch payment methods, should always be set to "web" for web apps (widget, b2c...). | string | false | "web" | | country | The country code where users are paying from. | string | false | "ES" | | currency | The currency applied to the payment methods. | string | true | "EUR" | | paymentAccountId | The id for any existing payment account, always undefined in the widget platform. | string | false | - |

• Xceed.prototype.createCheckout([options])

  This method create a checkout service, necessary for the creation of a dropin.

  It takes optional setting passed through an object:

  | Option | Description | Type | Required | Default | | ------ | ---------------------------------------------------------- | ------ | -------- | ------- | | locale | Represents the locale code for forms internationalization. | String | false | "es_ES" |

• Xceed.prototype.createDropin(checkoutInstance, [options])

  This method create a dropin instance, necessary for the XceedDropin component rendering.

  It takes a checkout instance as first argument and optional setting passed through an object as second:

  | Option | Description | Type | Required | Default | | ------------------ | ---------------------------------------------------------- | ------- | -------- | ------- | | enableStoreDetails | Show the checkbox to save used payment methods for a user. | Boolean | false | true |

• Xceed.fetchOriginKey()

  This static method fetch and return a promise with the response of an /origin-key request.

• Xceed.fetchPaymentMethods([options])

  This static method fetch the available payments methods based on some optons, currently used in the Xceed.prototype.init method.

  It takes optional setting passed through an object:

  | Option | Description | Type | Required | Default | | ---------------- | ------------------------------------------------------------------------------------------------------- | ------ | -------- | ------- | | amount | Represents the amount to pay for the current payment. | number | true | 20 | | channel | The channel used to fetch payment methods, should always be set to "web" for web apps (widget, b2c...). | string | false | "web" | | country | The country code where users are paying from. | string | false | "ES" | | currency | The currency applied to the payment methods. | string | true | "EUR" | | paymentAccountId | The id for any existing payment account, always undefined in the widget platform. | string | false | - |

• Xceed.addScripts()

  This static method adds and caches to the current document body the necessary scripts to create an Adyen checkout service.

• Xceed.createBooking(bookingData)

  This static async method attempt a booking and return the booking id in case of success.

  It takes an object as first argument with the required field:

  | Option | Description | Type | Required | Default | | ------------------ | ---------------------------------------------------------- | ------- | -------- | ------- | | enableStoreDetails | Show the checkbox to save used payment methods for a user. | Boolean | false | true |

• Xceed.generateTicket(form)

  This static async method generate a ticket, used when no payment is required.

  It takes a FormData as first argument with all the ticket buyer and ticket holders info:

  | Option | Description | Type | Required | Default | | ------ | ------------------------- | -------- | -------- | ------- | | form | Ticket buyer/holder info. | FormData | True | - |

• Xceed.pay(type, paymentRequest)

  This static async method send the payment for a booking.

  It takes a payment type endpoing as first argument and an object with the payment request data as second argument. Is recommended to not use this method without any other interface, since it's part of the checkout flow implemented for the XceedDropin component.

  | Option | Description | Type | Required | Default | | -------------- | ------------------------ | ------ | -------- | ------- | | type | Payment type endpoint. | string | true | - | | paymentRequest | Payment request details. | object | true | - |

• Xceed.submitAdditionalDetails(paymentId, additionalPaymentData)

  This static async method send the payment for a booking.

  It takes a payment id as first argument and an object with the additional payment data as second argument. Is recommended to not use this method without any other interface, since it's part of the checkout flow implemented for the XceedDropin component.

  | Option | Description | Type | Required | Default | | --------------------- | ------------------------ | ------ | -------- | ------- | | paymentId | Payment id | string | true | - | | additionalPaymentData | Additional payment data. | object | true | - |

XceedDropin

The XceedDropin component renders different parts of our checkout flow:

• Ticket Buyer form: always rendered when buying a ticket.
• Ticket holder form: rendered when a type of rsvp is marked as nominative and the user buys more than one ticket.
• Dropin payment form: rendered when the user has to pay at the online checkout, this section include all the available payments methods.

The component accepts some properties, some of them required:

| Property | Description | Type | Required | Default | | ------------------ | ------------------------------------------------------------ | ------------- | -------- | -------- | | dropin | Dropin instance added to the dropin state. | object | true | - | | setDropin | Setter for the dropin state. | function | true | - | | disabler | Disabler function for validation flags. | function | True | - | | bookingData | Object with booking related information. | object | true | - | | payment | Object with payment related information. | object | true | - | | formFields | Form fields with constrains for the ticket buyer. | array | false | [] | | ticketHolderFields | Form fields with constrains for the ticket holders. | array | false | [] | | lang | Form language. | string | false | "en" | | onSuccess | Function triggered after a successful payment/booking. | function | false | () => {} | | onFailure | Function triggered after a failed payment/booking. | function | false | () => {} | | onPending | Function triggered when a payment/booking flow starts. It also accept a clean up function as return value that will be executed when the paymente flow ends. | function | false | () => {} |

bookingData

The bookingData property should respect the following shape:

| Property | Description | Type | Required | | ---------- | -------------------------- | ------ | -------- | | rsvp | Rsvp id. | number | true | | prid | Promoter id. | number | true | | source | Booking source. | string | true | | numTickets | Number of tickets. | number | true | | price | Price for selected rsvp. | number | true | | fee | Fee for selected rsvp. | number | true | | widgetId | Id of the origin widget. | number | false | | eventId | Id of the current event. | number | true | | venueName | Name of the current venue. | string | true |

payment

The payment property should respect the following shape:

| Property | Description | Type | Required | | ------------------ | --------------------------------------------------------- | ------- | -------- | | amount | Amount to pay for the current transaction. | number | true | | country | Country where the current transaction is paid. | string | true | | currency | Currency for the current transaction. | string | true | | storePaymentMethod | Flag to render or not the "Save payment method" checkbox. | boolean | false |

formFields/ticketHolderFields

The formFields/ticketHolderFields property should respect the following shape:

[
	{ name: 'firstName', displayName: 'First Name', dataType: 'text', required: true },
  { name: 'lastName', displayName: 'Last Name', dataType: 'text', required: true },
  ...
]

Implementation details

• The formFields passed will be merged with a default set of fields which are always included.

Development

For more information about the development flow and how to contribute to this package, you can find all the details in the Xceed AdyenJS Wiki.

Contributors

• Marco Antonio Ghiani - Email - GitHub - LinkedIn

License

This project is licensed under the MIT License - see the LICENSE.md file for details.