> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Connect

> Charge your own customer's card in real time and keep a margin, with no prepaid Zinc balance.

Most Zinc accounts pre-fund a **prepaid wallet** that each order draws down. Stripe Connect is a new way to pay that skips the balance entirely.

Instead of drawing down a wallet, Zinc places a single **shared charge** on your own end-customer's card: one charge that covers the order cost, your margin, and our fee.

You keep your margin. Zinc keeps the cost (reimbursing the purchase it fronts for you) plus our standard \$1 fee. Every order funds itself, so there's nothing to top up.

## How It Works

Because the retailer's final total isn't known until checkout, Stripe Connect places a hold when the order goes in, then captures the final amount once Zinc places the order with the retailer and releases the rest of the hold.

**1. Connect your Stripe account**

In your [settings](https://app.zinc.com/settings), authorize Zinc against your existing Stripe account. You keep your keys, dashboard, and payouts. Set a **statement descriptor** your end-customers will recognize before enabling charges, so they aren't surprised by an unfamiliar line item.

**2. Place the order with a payment object**

Add a `payment` object to your [standard create-order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md) call, with `mode: "connect"`. Zinc authorizes a hold on your end-customer's card; if it's declined, no order is created.

**3. Zinc places the order**

Zinc places the order with the retailer, just like any other order.

**4. Capture the final total**

Once the order is placed with the retailer, Zinc captures the actual amount and releases the rest of the hold. Your margin settles to your Stripe account; Zinc keeps the order cost (reimbursing the purchase it fronted) plus our fee.

**Example:** a \$50.00 order with a flat \$2.50 margin:

| Component | Amount |
| - | - |
| Order cost (goods) | \$50.00 |
| Your margin | \$2.50 |
| Zinc fee | \$1.00 |
| Stripe fee (2.9% + \$0.30) | \$1.91 |
| **End-customer is charged** | **\$55.41** |
| → You receive (margin) | \$2.50 |
| → Zinc keeps (cost + fee) | \$51.00 |

> [!NOTE]
>
> Connect orders are funded by the end-customer's charge, so they never touch your Zinc wallet and don't appear in your wallet balance or transaction history.

## Placing a Connect Order

Add a `payment` object to your [standard create-order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md) call with `mode: "connect"`. Omit it (or send `mode: "wallet"`) for unchanged prepaid-wallet billing.

```bash theme={null}
curl https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{"url": "https://www.amazon.com/dp/B0EXAMPLE"}],
    "max_price": 6000,
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Smith",
      "address_line1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US",
      "phone_number": "2065551234"
    },
    "payment": {
      "mode": "connect",
      "payment_method": "pm_1ExampleCard",
      "customer": "cus_ExampleEndCustomer",
      "margin": { "type": "flat", "value": 250 }
    }
  }'
```

`max_price` is the most the **goods** can cost, the same ceiling used for any order; it does **not** include your margin or fees. Zinc holds that ceiling plus your margin, our \$1 fee, and Stripe's fee, then charges your customer only the actual total once the order is placed.

### The `payment` object

| Field | Required | Description |
| - | - | - |
| `mode` | | `"wallet"` (default) or `"connect"`. |
| `payment_method` | ✓ | Your end-customer's saved Stripe payment-method id (`pm_…`) on your connected account. |
| `customer` | ✓ | Your end-customer's Stripe Customer id (`cus_…`) on your connected account. The card is charged off-session, so Stripe requires the Customer it's saved on. |
| `margin` | ✓ | Your markup: `{ "type": "flat", "value": <cents> }` or `{ "type": "percent", "value": <percent> }` (e.g. `15` = 15%). |

> [!WARNING]
>
> The card must be vaulted on your connected account, not on Zinc. Zinc charges it off-session via Stripe Connect; it never sees or stores raw card details.

## Order Lifecycle & Refunds

* **Order fails:** the hold is voided and your end-customer's funds are released; nothing is captured.
* **Cancelled by the retailer after capture:** Zinc refunds your end-customer in full on your connected account, including the platform fee (Zinc keeps nothing on a cancelled order).
* **Successful order:** the actual total is captured; your margin settles to your account.

> [!NOTE]
>
> Refunds are issued server-side against the original charge on your connected account and follow Stripe's standard settlement timelines.

## Next Steps

> [card] [Create an Order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md)
>
> See the full create-order API spec, including the `payment` object.

> [card] [Connect your account](https://app.zinc.com/settings)
>
> Link your Stripe account in dashboard settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.