Quickstart Guide
Simplified flow for easier integration
Requirements
npm v7
or higherReact 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:
Parameter | Mandatory | Description |
---|---|---|
amount.value | Y | The amount in the payment charge, the currency's smallest unit. |
amount.currency | Y | ISO 4217 3-letter code of the payment charge currency. |
recurring | Y | True if it is a recurring transaction. |
consumer.country | Y | ISO 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.
Parameter | Description |
---|---|
onSubmitPayment | Callback function to listen for the Submit event. This event is generated when the consumer clicks the payment button. |
onPaymentResult | Triggered by the final status of the payment - if the payment either succeeds or fails. |
locale | Localises the checkout to the selected language and region. |
appearance | Drop-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 7 days ago