Embedded Quick Start

Get started with embedded fields.

Use the instructions below to quickly set up embedded fields for transactions. See Payments to customize and add optional features for payments with this integration method.

Prerequisites

Integrate

Follow the steps below to create a basic web page that opens a payment form when a customer clicks a 'Pay Now' button:

  1. Copy and paste the code below into a text file and save it as an HTML file:
<!doctype html>
<head>
  <style>#qp-embedded-container { border: 1px solid black; }</style>
  <link rel="stylesheet" href="https://app.qualpay.com/hosted/embedded/css/qp-embedded.css">
</head>
<body>
  <script src="https://app.qualpay.com/hosted/embedded/js/qp-embedded-sdk.min.js"></script>

  <form id="my-payment-form" method="post" action="/">
    <div id="qp-embedded-container" align="center"></div>
    <script>
      qpEmbeddedForm.loadFrame({{merchant_id}},                // merchant ID
        {
          formId: "my-payment-form",
          mode: "test",                                     // change mode between "test" and "prod"
          transientKey: "{{transient_key}}", // transient key
          tokenize: true,                                   // set to true to make card_id permanent
          onSuccess: (data) => {
            const { card_id, card_number } = data;
            console.log(data);
            alert( "card id is "+ card_id +", card number is "+ card_number );
            // Make payment from server using the token
          },
          onError: (error) => {
            if( error.detail ) {
              for( let key in error.detail ) {
                console.log(error.detail[key]);
              }
            }
          },
          cardConfig: {
            enabled: true,
          },
          achConfig: {
            enabled: true,
            onPaymentTypeChange: function (data) {
              console.log("Display ", data);
            },
          },
          formFields: {
            cvv2: {
              required: true
            }
          },
          font: 'Titillium Web',
          style:
            "#root { min-width: 260px; }" +
            ".content {" +
            "  background-color: #35F;" +
            "  font-family: 'Titillium Web';" +
            "}",
        });
    </script>
    <input type="submit" name="submit" value="Pay Now"></input>
  </form>
</body>
</html>
  1. Send a request to the API endpoint /platform/embedded to get a transient key. See Get Transient Key in our API reference for details. You will need your sandbox API key to authenticate your request.

  2. Replace {{transient_key}} on line 15 of the sample code with the transient key returned by the API. Save the HTML file.

  3. Replace {{merchant_id}} on line 12 of the sample code with your merchant ID. It is the same merchant ID you used to get the transient key.

  4. Save the updated HTML file.

  5. Open the HTML file in your browser. You should see a payment form with a Pay Now button.

The code above includes the Qualpay embedded fields stylesheet, which makes it easy to customize the appearance of the payment form, and the Qualpay Embedded JavaScript, which facilitates the communication between your site and Qualpay's servers. See the embedded fields Payments guide for details about using the Checkout JavaScript to process transactions.

📘

ACH Payments

NOTE: If your account is set up to receive ACH payments, you must meet ACH consent statement and validation requirements. See ACH Conventions for more information.

Test and Go Live

See our Test and Go Live guide to test your embedded fields integration and to start transacting with an active production account.

📘

Change API and JavaScript

When moving to production with an embedded fields integration, don't forget to change both your API request and your JavaScript to production values.


Did this page help you?