# Form Configuration

# Form Configuration

The Hosted Payment Form supports configuration options that allow you to customize its appearance and behavior. Use the `formConfig` object in your API requests to control how the payment form collects billing information.

## Billing Information Capture Levels

<div style="padding-left: 20px; border-left: 3px solid #0969da; margin-bottom: 20px;">
The <code>billingInfoCaptureLevel</code> property controls how much billing information is collected from the customer. There are two options:

<ul style="padding-left: 40px;">
  <li><strong>Full</strong> (Default) - Collects complete billing address including street address, city, state, country, and ZIP/postal code. This is the default if no <code>formConfig</code> is specified.</li>
  <li><strong>Minimal</strong> - Collects only the ZIP/postal code, displayed inline with the card fields for a streamlined checkout experience.</li>
</ul>
</div>

## Full Billing Mode (Default)

<div style="margin-bottom: 20px;">
  <p>When <code>billingInfoCaptureLevel</code> is set to <code>Full</code> (or when no <code>formConfig</code> is provided), the form displays complete billing address fields:</p>

  <div style="margin-bottom: 30px;">
    <img src="https://static.integratedcommerce.io/docs/hpf.png" alt="Hosted Payment Form - Full Billing" style="max-width: 100%; height: auto;" />
    <small style="display: block; margin-top: 5px; opacity: 0.7;">Full billing mode collects complete address information</small>
  </div>
</div>

## Compact Form Mode (Minimal Billing)

<div style="margin-bottom: 20px;">
  <p>When <code>billingInfoCaptureLevel</code> is set to <code>Minimal</code>, the form displays a compact layout with only the ZIP/postal code field shown inline with the card fields:</p>

  <div style="margin-bottom: 30px;">
    <img src="https://static.integratedcommerce.io/docs/hpf-compact.png" alt="Hosted Payment Form - Compact/Minimal Billing" style="max-width: 100%; height: auto;" />
    <small style="display: block; margin-top: 5px; opacity: 0.7;">Compact form mode with minimal billing (ZIP code only)</small>
  </div>

  <p>This compact form is ideal for scenarios where:</p>
  <ul style="padding-left: 40px;">
    <li>You want to minimize friction in the checkout process</li>
    <li>Full address information is not required for your business needs</li>
    <li>You're processing card-not-present transactions where basic AVS (ZIP code) verification is sufficient</li>
  </ul>
</div>

## Usage Example

<div style="padding-left: 20px; border-left: 3px solid #0969da; margin-bottom: 20px;">
<p>Include the <code>formConfig</code> object in your request to customize the form:</p>

```json
{
  "amount": 1000,
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "invoiceNumber": "inv_12345",
  "formConfig": {
    "billingInfoCaptureLevel": "Minimal"
  }
}
```
</div>

## ACH Payment Method Restrictions

<div style="padding-left: 20px; border-left: 3px solid #f87171; margin-bottom: 20px;">
<strong>Important:</strong> ACH payment methods always require full billing information. The <code>Minimal</code> billing capture level is <strong>not supported</strong> for ACH transactions. If you attempt to use <code>billingInfoCaptureLevel: Minimal</code> with an ACH payment method, the request will be rejected with a validation error.
</div>

## Form Configuration Properties

<div style="overflow-x: auto; margin-bottom: 20px;">
  <table style="width: 100%; border-collapse: collapse;">
    <thead>
      <tr style="background-color: rgba(240, 244, 248, 0.15);">
        <th style="padding: 10px; text-align: left; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">Property</th>
        <th style="padding: 10px; text-align: left; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">Type</th>
        <th style="padding: 10px; text-align: left; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">Default</th>
        <th style="padding: 10px; text-align: left; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td style="padding: 10px; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;"><code>billingInfoCaptureLevel</code></td>
        <td style="padding: 10px; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">string</td>
        <td style="padding: 10px; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;"><code>Full</code></td>
        <td style="padding: 10px; border: 1px solid rgba(225, 228, 232, 0.2); color: inherit;">Controls billing information collection. Values: <code>Full</code>, <code>Minimal</code></td>
      </tr>
    </tbody>
  </table>
</div>