# Stripe Payments

> Configure Stripe to collect payments during document signing and in Smart Signing Forms payment fields.

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/integrations/stripe/
Markdown: https://docs.wpsigner.com/md/integrations/stripe.md
Source file: integrations/stripe.md

---

Collect payments with **Stripe** inside WPsigner. The same Stripe configuration powers:

- **Payment fields** on the document signing page (signers pay before completing)
- **Payment fields** in [Smart Signing Forms](/addons/smart-signing-forms/) (addon)

> **note**
Stripe must be **enabled** under **WPsigner → Integrations** before you open the Stripe settings page.

---

## Prerequisites

- **WPsigner** v3.0.0 or later (Stripe integration v3.21+)
- A [Stripe account](https://dashboard.stripe.com/register)
- **HTTPS** on your WordPress site (required for live payments and webhooks)
- For Smart Forms payments: [Smart Signing Forms](/addons/smart-signing-forms/) installed and activated

---

## Enable Stripe

1. Go to **WPsigner → Integrations**
2. Find the **Stripe** card
3. Toggle the integration **On**
4. Click **Configure** to open Stripe settings

---

## Environment Mode

WPsigner stores **separate keys** for test and live mode.

| Mode | Use when |
|------|----------|
| **Test Mode** | Setting up, testing cards, staging sites |
| **Live Mode** | Real customer payments on production |

Switch mode with the **Test Mode / Live Mode** toggle at the top of the Stripe settings page. Only the keys for the active mode are used for payments and webhooks.

> **tip**
Use [Stripe test cards](https://docs.stripe.com/testing) (for example `4242 4242 4242 4242`) while Test Mode is active.

---

## API Keys

Get keys from the [Stripe Dashboard](https://dashboard.stripe.com/apikeys) (use the **test** dashboard when in Test Mode).

| Field | Description |
|-------|-------------|
| **Publishable Key** | Starts with `pk_test_` or `pk_live_`. Safe to use in the browser. |
| **Restricted Key** | Starts with `rk_test_` or `rk_live_`. **Recommended** — limit permissions to what WPsigner needs. |
| **Secret Key** | Starts with `sk_test_` or `sk_live_`. Supported for compatibility; prefer restricted keys when possible. |

Keys are stored encrypted on your server when OpenSSL is available.

### Default Currency

Choose the default currency for payment fields:

**USD**, **EUR**, **GBP**, **CAD**, **AUD**, **MXN**, **BRL**, **COP**

Individual Smart Form payment fields can override the currency per form.

---

## Webhook Configuration

Webhooks let WPsigner receive payment status updates from Stripe (succeeded, failed, disputes, refunds).

### Webhook URL

Copy the URL shown on the Stripe settings page:

```
https://your-site.com/wp-json/insigner/v1/stripe-webhook
```

Replace `your-site.com` with your WordPress site URL.

### Required Events

Enable these events in Stripe (or use **Create Webhook Automatically** in WPsigner):

| Event | Purpose |
|-------|---------|
| `payment_intent.succeeded` | Mark payment as completed |
| `payment_intent.payment_failed` | Handle failed attempts |
| `payment_intent.canceled` | Handle canceled intents |
| `charge.dispute.created` | Dispute notifications |
| `charge.refunded` | Refund tracking |

### Setup Options

**Option A — Automatic (recommended)**

1. Save your API keys first
2. Click **Create Webhook Automatically**
3. WPsigner registers the endpoint in Stripe and stores the signing secret

**Option B — Manual**

1. In [Stripe Webhooks](https://dashboard.stripe.com/webhooks), add the endpoint URL above
2. Select the events listed above
3. Copy the **Signing secret** (`whsec_...`)
4. Paste it into WPsigner and save

> **caution**
Use **test** webhooks with test keys and **live** webhooks with live keys. Mixing modes causes missed events.

---

## Test Connection

After saving keys:

1. Click **Test Connection**
2. WPsigner verifies the secret/restricted key against the Stripe API
3. Fix any errors before switching to Live Mode

---

## Payment on Document Signing

When a document includes a **Payment** field:

1. The signer completes payment in the signing UI (Stripe Payment Element)
2. WPsigner verifies the PaymentIntent on the server before the signature is accepted
3. Webhooks keep payment status in sync

Configure payment fields when creating or editing a document in the field editor.

---

## Payment in Smart Signing Forms

Smart Signing Forms uses the **same Stripe settings** as the core plugin.

1. Complete this Stripe setup first
2. In the Smart Forms builder, add a **Payment** field (one per form)
3. Set amount (minimum **0.50**, maximum **10,000** in the configured currency)
4. Signers enter a valid email, pay with **Pay now**, then sign and submit

See the full guide: [Smart Signing Forms — Payment field](/addons/smart-signing-forms/#payment-field-stripe)

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| **Not Connected** status | Enter both publishable and secret/restricted keys for the active mode |
| Test Connection fails | Verify key prefix matches mode (`pk_test_` + `rk_test_` in Test Mode) |
| Payments work but status not updating | Check webhook URL, signing secret, and required events |
| Smart Form shows "Stripe not configured" | Enable Stripe module and save valid keys |
| "Complete payment before submitting" | Signer must click **Pay now** and wait for success before **Submit & Sign** |
| Test badge still visible in production | Switch to **Live Mode** and use live keys |

### Debug Logging

Enable WordPress debug logging to inspect Stripe-related errors:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

Check `wp-content/debug.log` for entries related to Stripe or Smart Forms payments.

---

## Next Steps

- [Smart Signing Forms](/addons/smart-signing-forms/) — Build forms with inline signature and payment
- [Form Fields](/core-features/form-fields/) — Payment fields on PDF documents
- [Account Portal](/addons/account-portal/) — Download plugins and addons with your license