Embedded Payments Session Integration
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
{
"merchantId": "1cc7b594-b80f-4227-a0fa-299c4c6ce8ab",
"data": {
"type":"payment_session",
"amount": 12.50,
"currencyCode": "USD",
"paymentMethods": ["CC_DC","ACH"],
"oneTimeOnly":true,
"salesTax": 2.50,
"orderNumber": "A350",
"startDate": "20220510",
"endDate": "20221115",
"description": "A coffee cup in the morning",
"saveCardConsent": true,
"internalTransactionID": "ID1",
"customer":{
"first_name":"John",
"last_name":"Doe",
"business_name":"",
"address":{
"street":"100 Main Street",
"unit":"80",
"city":"Austin",
"state":"Texas",
"country":"us",
"postal_code":"76707",
},
"email":"[email protected]",
"phone":{
"country_code":"1",
"subscriber":"8042773232"
}
},
"success_text":"Thank you! Your payment has been successfully processed`",
"failure_text":"Payment failed. Please try again",
"metadata": {
"customerId": "123",
"email" : "[email protected]"
}
}
}Sample response
{
"data": {
"paymentLinkId": "wlx57",
"merchantId": "1cc7b594-b80f-4227-a0fa-299c4c6ce8ab",
"type":"payment_session",
"amount": "12.50",
"currencyCode": "USD",
"paymentMethods": ["CC_DC","ACH"],
"oneTimeOnly":true,
"salesTax": "2.50",
"orderNumber": "A350",
"description": "A coffee cup in the morning",
"startDate": "2022-05-10T00:00:00.000Z",
"endDate": "2022-11-15T00:00:00.000Z",
"createdAt": "2022-09-11T03:36:42.113Z",
"updatedAt": "2022-09-11T03:36:42.113Z",
"paymentLinkStatus": "ACTIVE",
"paymentLinkUrl": "<Payment URL>",
"qrCodeUrl": "<QRCode Image URL>",
"internalTransactionID": "ID1",
"customer":{
"first_name":"John",
"last_name":"Doe",
"business_name":"",
"address":{
"street":"100 Main Street",
"unit":"80",
"city":"Austin",
"state":"Texas",
"country":"us",
"postal_code":"76707",
},
"email":"[email protected]",
"phone":{
"country_code":"1",
"subscriber":"8042773232"
}
},
"success_text":"Thank you! Your payment has been successfully processed",
"failure_text":"Payment failed. Please try again",
"metadata": {
"customerId": "123",
"email" : "[email protected]"
}
}
}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.
<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"
payment-link-id="2c38bace-5f3a-4ebc-a7a5-3a1bb46b184d"
shouldProcess3ds="true" // Optional. Default is false
onTransactionEvent="handleTransaction"
/>
2b. Display the payment session using client side JS
// To open the payment session modal
const {close, container} = Platform.PaymentSession.open({
container: <container>, // Optional: DOM Element or element id where
// form will be rendered
paymentLinkId: <your-payment-link-id>, // 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();
Step 3 (webhook event)
Once the payment is completed, a PAYMENTLINK_PAID webhook event will be sent with the transaction ID.
Sample webhook
{
"event_uid": "524c9d172633168746f5408af7013410",
"event": "PAYMENTLINK_PAID",
"data": {
"type":"payment_session",
"id": "0elwh",
"name": "My payment link",
"amount": "1000.00",
"isPaid": true,
"slugId": null,
"endDate": null,
"success": true,
"ccAmount": null,
"salesTax": null,
"achAmount": null,
"createdAt": "2025-04-08T17:39:35.765Z",
"startDate": "2025-04-08T17:37:00.000Z",
"updatedAt": "2025-04-08T17:39:35.765Z",
"account_id": "d23ca259-1e39-4b84-8bd1-bbcb5de8d24b",
"merchantId": "2219b585-7e41-46f8-bf42-928a1f81ffef",
"contactInfo": true,
"description": null,
"isCancelled": false,
"oneTimeOnly": true,
"orderNumber": null,
"ccAmountNote": null,
"currencyCode": "USD",
"merchantName": "My Merchant, LLC",
"achAmountNote": null,
"enableCaptcha": false,
"transactionId": "c76003f5-311d-2652-a293-9a37909e7dff",
"useSameAmount": true,
"paymentMethods": [
"CC_DC"
],
"saveCardConsent": false,
"contactInfoDetails": {
"showAddress": true,
"showLastName": true,
"showFirstName": true,
"showPhoneNumber": true,
"mandatoryAddress": true,
"showBusinessName": true,
"showEmailAddress": true,
"mandatoryLastName": true,
"mandatoryFirstName": true,
"mandatoryPhoneNumber": true,
"mandatoryBusinessName": false,
"mandatoryEmailAddress": true
},
"customer":{
"first_name":"John",
"last_name":"Doe",
"business_name":"",
"address":{
"street":"100 Main Street",
"unit":"80",
"city":"Austin"
"state":"Texas",
"country":"us",
"postal_code":"76707",
},
"email":"[email protected]",
"phone":{
"country_code":"1",
"subscriber":"8042773232"
}
},
"success_text":"Thank you! Your payment has been successfully processed",
"failure_text":"Payment failed. Please try again",
"internalTransactionID": ""
}
}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.
GET https://<Platform-host>/api/merchant/:merchant_id/transaction/:transaction_id
Sample response
{
"data": {
"id": "20655494-8713-47d9-9553-ec2acd959a2e",
"amount": "110.00",
"is_offline": false,
"standalone": false,
"isOverridenTransaction": false,
"refundable": true,
"voidable": false,
"details": [
{
"id": "b48cf399-9e32-4733-9145-c586e5cf3a74",
"external_id": "35265177",
"currency": "USD",
"requested_currency": "USD",
"amount": "110.00",
"currency_conversion_rate": null,
"requested_amount": "110.00",
"data": {
"last_4": "1111",
"card_type": "visa",
"card_id": "d49d99e6-9b79-4f54-8284-d8f8054574c9",
"card_token":"card_prod_c6rUWsHcLLmDzKkzgkJlwqc8",
"bank_account_id": null,
"bank_account_token": null,
"sales_tax": "10.00",
"order_number": "Order124",
"first_name": "card holder",
"last_name": "name",
"customer_name": "John Doe",
"accounting_data": {
"salesTax": "10.00",
"orderNumber": "Order124"
},
"ip_address": "10.10.10.10"
},
"host_report": {
"status": "PASS",
"responseCode": "A0000",
"responseMessage": "Success",
"authCode": "594450",
"hostResponseCode": "00",
"hostReferenceNumber": "695565385087",
"taskID": "88208569",
"transactionID": "35265177",
"transactionTimestamp": "2025-04-02T19:15:20",
"transactionAmount": "110.00",
"processedAmount": "110.00",
"totalAmount": "110.00",
"addressVerificationCode": "X",
"cardHolderVerificationCode": "N",
"cardType": "visa",
"maskedCardNumber": "1111",
"customerReceipt": " Sandbox US Merchant \\n 200 Epcot Center Dr \\n Orlando, FL 32836 \\n 800-490-8514 \\n \\n \\n 2025-04-02 07:15 PM \\n CREDIT - SALE \\n Entry Mode : KEYED \\n Transaction ID: 35265177 \\n Invoice Number: Order124 \\nDescription: Payment for the service\\n s \\n SUBTOTAL: USD $100.00 \\n SALES TAX: USD $10.00 \\n TOTAL: USD $110.00 \\n \\n \\n NO SIGNATURE REQUIRED \\n APPROVED \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n Customer Copy \\n",
"merchantReceipt": " Sandbox US Merchant \\n 200 Epcot Center Dr \\n Orlando, FL 32836 \\n 800-490-8514 \\n \\n \\n 2025-04-02 07:15 PM \\n CREDIT - SALE \\n Entry Mode : KEYED \\n Transaction ID: 35265177 \\n Invoice Number: Order124 \\nDescription: Payment for the service\\n s \\n SUBTOTAL: USD $100.00 \\n SALES TAX: USD $10.00 \\n TOTAL: USD $110.00 \\n \\n \\n X_______________________ \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n OUCHER) \\n KEEP COPY FOR YOUR RECORDS \\n \\n \\n \\n APPROVED \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n Merchant Copy \\n",
"partialPayment": false,
"providedSalesTax": true
},
"kount_score": null,
"card_type": "visa",
"last_4": "1111",
"payment_method": "Credit Card",
"status": "succeeded",
"fee_amount": null,
"net_amount": "110.00",
"type": "payment",
"is_offline": false,
"updated_at": "2025-04-02T19:15:20.839Z",
"created_at": "2025-04-02T19:15:20.839Z",
"description": "Payment for the services",
"auth_datetime": "2025-04-02T19:15:20.839Z",
"capture_datetime": "2025-04-02T19:15:20.839Z",
"internalTransactionID": "987654321",
"batch_id": null,
"refund_type": null,
"fee_type": null,
"presettlement_fee": null,
"merchant_gateway_override_id": null,
"metadata": null,
"threeds_auth_data": null,
"gateway": "sandbox",
"gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
"customer_name": "John Doe",
"settled": false
}
],
"partialAllowed": true
}
}Last updated