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"
  hash="bf7bc757c2893ed54ca002a5776e468c56dbbc75288ff117aa41e0fb806bc126"
  payment-link-id="2c38b"
  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} = 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();

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://<PayEngine-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
    }
}