> ## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Place the order with a payment object">
    Add a `payment` object to your [standard create-order](/docs/v2/api-reference/orders/create-order) call, with `mode: "connect"`. Zinc authorizes a hold on your end-customer's card; if it's declined, no order is created.
  </Step>

  <Step title="Zinc places the order">
    Zinc places the order with the retailer, just like any other order.
  </Step>

  <Step title="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.
  </Step>
</Steps>

**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     |

<Info>
  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.
</Info>

## Placing a Connect Order

Add a `payment` object to your [standard create-order](/docs/v2/api-reference/orders/create-order) 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.
</Warning>

## 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.

<Info>
  Refunds are issued server-side against the original charge on your connected account and follow Stripe's standard settlement timelines.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create an Order" icon="cart-shopping" href="/docs/v2/api-reference/orders/create-order">
    See the full create-order API spec, including the `payment` object.
  </Card>

  <Card title="Connect your account" icon="gear" href="https://app.zinc.com/settings">
    Link your Stripe account in dashboard settings.
  </Card>
</CardGroup>