Documentation

Quickstart Guide

Simplified flow for easier integration

The Drop-in Checkout makes it very simple to offer a global payment methods. It handles the complexity of localization and the different payment flows and authentication methods so that you don't have it. Furthermore, it has features for a higher authorization rate, for example, inputs are validated with clear error messages when a validation fails.

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.
autoCaptureTrue if the payment charge should be automatically captured after a successful authorization.
order.installmentPlan. numberOfInstallmentsDescribes number of installments the consumer will split the payment into.

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

Request example

{
    "amount": {
        "value": 20000,
        "currency": "BRL"
    },
    "recurring": false,
  	"autoCapture":true,
    "consumer": {
        "name": "Ada Lovelace",
        "country": "BR"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.ppro.com/"
            }
        },
        {
            "type": "SCAN_CODE",
            "settings": {
                "scanBy": "2025-11-03T11:23:47.123Z"
            }
        }
    ],
    "merchantPaymentChargeReference": "merchantPaymentChargeReference",
    "paymentDescriptor": "paymentDescriptor"

}

Response example

{
    "id": "sess_bAyBHO8DdnCILr0KwJGeg",
    "status": "INITIATED",
    "amount": {
        "value": 20000,
        "currency": "BRL"
    },
    "recurring": false,
    "consumer": {
        "name": "Ada Lovelace",
        "country": "BR"
    },
    "recommendedPaymentMethods": [
        "CARD", "PIX", "BOLETO"
    ],
    "expiresAt": "2025-11-01T11:23:47.123Z",
    "createdAt": "2025-11-01T11:23:47.123Z"
}

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({ paymentSession });

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: Customize the Drop-in Checkout options

There are many options for customizing 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.
localeLocalizes 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 storybook.

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


Card specific options

PPRO's Drop-in Checkout has features that are specific for card payments and allows for high level of customization.

You can render the available card form on your checkout to securely collect card information, so sensitive data does not reach your server. Out-of-the box, while the shopper is entering their card details, Drop-in Checkout tries to recognize the card brand. When successful, Drop-in renders the brand icon and the hint for the security code accurately describes it's placement.

To customize the card form fields as part of the forms.card object, you can use the following properties:

PropertyDescriptionDefault
hideHolderNameFieldSet to true to not display the input field for the card holder name.FALSE
displayBillingAddressFieldsSet to true to collect the shopper's billing address.FALSE
displayCheckboxToUseShippingAddressSet to true to display a checked checkbox. A consumer can uncheck to add a billing address if this is different to the shipping address.FALSE
hideCvvFieldSet to true to not collect security code.FALSE
displayTaxNumberFieldSet to true to collect the tax ID.FALSE

We recommend to always collect the card holder name and the security code. For some markets, it's required to collect the billing address or tax number. Please refer to our card documentation for more information.

Also, you can customize the brand preference:

PropertyDescriptionDefault
allowedBrandsAllows to specify exactly which card brands are accepted.
For Example: ["VISA", "DINERS", "DISCOVER","AMEX"]		All brands are accepted
brandDetectionPriorityAn array of brands that changes the order that the logos are displayed in the UI.
Example: ["ELO", "HIPERCARD", "MASTER", "VISA", "DINERS", "DISCOVER","AMEX"]		All brands are accepted

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 23 days ago