Enables partners to embed a hosted checkout form that offloads PCI scope, enforces AVS/3DS, and returns reusable card‑on‑file tokens. Additionally, the embedded payments form supports completing a full payment intent—pre‑baking the amount and transaction details—and executes the sale in a single call, returning the complete transaction result. This approach simplifies PCI compliance, reduces development effort, and provides a consistent user experience.
Example flow of embedded payments form integration using payment links
Step 1 (backend)
Call the Create Payment Link API with your Private API key to get the payment link ID. Pass details such as merchant ID, currency, amount, cardholder name, address, phone, email etc.
Sample request
Sample response
Step 2 (client side)
2a. Display the payment session web component, use a custom callback handler to receive the transaction response on the client side.
2b. Display the payment session using client side JS
Step 3 (webhook event)
Once the payment is completed, a PAYMENTLINK_PAID webhook event will be sent with the transaction ID.
Sample webhook
Step 4 (transaction details)
Based on transaction ID received in the webhook, you can retrieve the transaction details such as the card/bank account token using transaction detail endpoint.
<script>
function handleTransaction(evt) {
const { status, data, error } = evt.detail;
// data will include sale response object
switch (status) {
case 'success':
console.log('Payment succeeded:', data);
break;
case 'failure':
console.error('Payment failed:', data);
break;
case 'cancel':
console.log('Payment cancelled by user.');
break;
case 'error':
console.error('Could not open payment session:', error);
break;
}
}
</script>
<payengine
type="payment-session"
hash="bf7bc757c2893ed54ca002a5776e468c56dbbc75288ff117aa41e0fb806bc126"
payment-link-id="2c38b"
shouldProcess3ds="true" // Optional. Default is false
onTransactionEvent="handleTransaction"
/>
// To open the payment session modal
const {close, container} = PayEngine.PaymentSession.open({
container: <container>, // Optional: DOM Element or element id where
// form will be rendered
paymentLinkId: "<your-payment-link-id>", // Required
hash: "<your-hash>", // Required
shouldProcess3ds: false // Optional: Set to true if 3DS processing is required
},
(event) => {
// Handle payment session events
const { status, data, error } = event.detail;
switch (status) {
case "success":
// Handle successful payment
break;
case "failure":
// Handle failed payment
break;
case "cancel":
// Handle cancellation
break;
case "error":
// Handle error
break;
}
});
// To forcefully close the payment session modal
close();
