Documentation

Quickstart Guide

Simplified flow for easier integration

Requirements

  • npm v7 or higher
  • React 16.8 or higher (for React version)

Step 1: Install the NPM module

The Drop-in Checkout is delivered as a NPM module for easier installation and version management. It’s available in React as well as a JavaScript only variant.

You can install the NPM module by running npm install @pprogroup/drop-in-checkout

Step 2: Create a payment session

A payment session expects basic details about the consumer and their payment. It gives PPRO the necessary information to recommend suitable local payment methods and authorize the payment.

On your backend, make a POST /payment-sessions request on your backend, including:

ParameterMandatoryDescription
amount.valueYThe amount in the payment charge, the currency's smallest unit.
amount.currencyYISO 4217 3-letter code of the payment charge currency.
recurringYTrue if it is a recurring transaction.
consumer.countryYISO country code of where the consumer is based.
consumer.name(Recommended)The first and last name of the consumer.

To see the full list of parameters, please go to API documentation.

Request example

{
   "amount":{
      "value": 1000,
      "currency": "EUR",
      "type": "MAX"
   },
   "recurring": true,
   "consumer": {
      "name": "Conner Summer",
      "country": "NL"
   },
   "webhooksUrl": "https://webhooksUrl/",
   "authenticationSettings":[
      {
         "type":"REDIRECT",
         "settings":{
            "returnUrl": "https://example.com/order_details?order_id=12345"
         }
      }
   ]
}

Response example

{
  "id": "sess_WAyDCQoCObJ2prhUIEJDS",
  "amount": {
     "value": 1000,
     "currency": "EUR"
  },
  "recurring": true,
  "consumer": {
      "name": "Conner Summer",
      "country": "NL"
  },
  "recommendedPaymentMethods": ["IDEAL", "SEPA_DIRECT_DEBIT"],
  "expiresAt": "2024-05-28 18:00:00.000",
  "createdAt": "2024-05-28 17:00:00.000"
}

Step 3: Render the Drop-in Checkout component

Use the created paymentSession when you initialize the Drop-in Checkout component.

  • For the React version, pass paymentSession as a React property.
  • For the HTML version, pass paymentSession as an option.
import { DropInCheckout } from "@pprogroup/drop-in-checkout";

const MyCheckoutComponent = () => {
  
  (...)
   
  return (
    <DropInCheckout
      paymentSession={paymentSession}
      onPaymentResult={onPaymentResult}
      onSubmitPayment={onSubmitPayment}
    />
  );
};


import { PPRO } from "@pprogroup/drop-in-checkout";

const options = {
  paymentSession,
  onPaymentResult,
  onSubmitPayment
};

const dropInCheckout = PPRO.createDropInCheckout(options);
dropInCheckout.mount("#checkout-element");

(...)
dropInCheckout.update(

If you're using the HTML version, you can see the available methods for dropInCheckout here:
https://storybook.drop-in-checkout.ppro.com/?path=/docs/exports-usedropincheckout--docs#available-methods

Step 4: Customise the Drop-in Checkout options

There are many options for customising the look and behavior of the Drop-in Checkout, so that it seamlessly blends in with your checkout.

ParameterDescription
onSubmitPaymentCallback function to listen for the Submit event. This event is generated when the consumer clicks the payment button.
onPaymentResultTriggered by the final status of the payment - if the payment either succeeds or fails.
localeLocalises the checkout to the selected language and region.
appearanceDrop-in Checkout appearance and theming options for the elements.
openFirstPaymentMethod When enabled, the first payment method is preselected and opens automatically on page load.

For a full list of available options, please see: https://storybook.drop-in-checkout.ppro.com/?path=/docs/dropincheckout-props--docs.

All the React properties have equivalent HTML version options (please see the example from step 3).

Step 5: Handle the payment submission

Depending on the payment flow that you've chosen, to handle the payment submission, you need to provide either:

a) preSubmitPayment- for Basic flow
b) onSubmitPayment - for Advanced flow

This method will be run when the user clicks Submit Payment button.

import {
  DropInCheckout,
  PaymentMethodId,
  PaymentSession,
  PreSubmitPaymentCallback,
  SubmitPaymentData,
} from "@pprogroup/drop-in-checkout";
import pproAPIConfig from "@/util/pproAPIConfig";

import onPaymentResult from "./onPaymentResult";
import debitMandateConfig from "@/util/debitMandateConfig";

const preSubmitPayment: PreSubmitPaymentCallback = async ({
  paymentMethodId,
  inputData,
}: SubmitPaymentData) => {
  // We can do front-end validation here
  if (
    paymentMethodId === "SEPA_DIRECT_DEBIT" &&
    (inputData.firstName as string).indexOf("ValidationError") !== -1
  ) {
    return {
      status: "ERROR",
      errorMessage: "Name validation failed browser-side",
    };
  } else {
    // We can also do any server calls here, ie:
    // const { status, errorMessage } = await adobeAPI.validatePayment();
    // return { status: "ERROR", errorMessage: "Fraud check failed" };
  }

  // if input has debitMandate - attach debitMandateId
  if (inputData.debitMandate) {
    return {
      status: "OK",
      additionalData: {
        // Provide the mandate ID to the authorization request
        debitMandateId: "DE-12345678901",
      },
    };
  }

  return { status: "OK" };
};


import {
  DropInCheckout,
  PaymentMethodId,
  PaymentSession,
  OnSubmitPaymentCallback,
  SubmitPaymentData,
} from "@pprogroup/drop-in-checkout";
import pproAPIConfig from "@/util/pproAPIConfig";

import onPaymentResult from "./onPaymentResult";
import debitMandateConfig from "@/util/debitMandateConfig";

const onSubmitPayment: OnSubmitPaymentCallback = async ({
  paymentMethodId,
  inputData,
  paymentSessionId,
}: SubmitPaymentData) => {
  const res = await fetch("/api/submit-payment", {
    method: "POST",
    body: JSON.stringify({ paymentSessionId, paymentMethodId, inputData }),
  });
  const { status, errorMessage, paymentAuthResponse } = await res.json();
  return { status, errorMessage, paymentAuthResponse };
};

For more documentation and API specification, see the links below:

Step 6: Handle the payment result

onPaymentResult is called to communicate the final status of a payment session.

The exception is when a full-page redirect (not a popup) is used, and the user is redirected out of the merchant's website and the Drop-in Checkout.

You can use the Payment Result to:

  • render the receipt page to the consumer
  • redirect the consumer to the receipt page
  • handle errors
import { PaymentSessionId, PaymentResult } from "@pprogroup/drop-in-checkout";

const onPaymentResult = (
  paymentResult: PaymentResult,
  paymentSessionId: PaymentSessionId
) => {
  console.log("Payment result", paymentResult);
  const { status, message } = paymentResult;

  /**
   * Redirect - please uncomment the line below if instead of redirecting
   * to the receipt page, you would like to:
   * - inspect network calls
   * - inspect SSE messages (console logged - verbose level)
   */
  window.location.href = `/receipt?status=${status}&message=${message ?? ""}`;

  /**
   * Alternatively, we can pass paymentSessionId and let the server
   * fetch PaymentResult from the Payment Sessions API
   */
  // window.location.href = `/receipt?pproSessionId=${paymentSessionId}`;
};

Step 7: Process the payment outcome

You will receive payment status updates via webhooks.

The expected response from you is an HTTP 2XX to indicate that they received the webhook request. If a webhook delivery is not acknowledged, we automatically retry the delivery according to an exponential backoff model.

You can find more information about webhooks: https://developerhub.ppro.com/global-api/docs/webhooks.

📘

Playground app

You can find the sample integration of Drop-in Checkout here:
https://playground.drop-in-checkout.ppro.com/

Updated 25 days ago