# Dime Bridge™ — Split Payments

Dime Bridge lets you split a single customer payment across **multiple merchants** in your marketplace and collect a **platform fee per merchant**

This README shows how to **create an Order** with the Dime Bridge payload and how item-level tagging ties each line item to a merchant split.

**Version:** 1.0.0

## When to use Dime Bridge

Use Dime Bridge any time a single checkout involves **more than one seller** (merchant) and you need:

- Per-merchant revenue allocation derived from product totals, and
- A platform fee per merchant (`split[].fee`).


> **Note:** `split[].amount` is no longer sent by the merchant. Dime derives the merchant payout from the tagged product totals, then applies MDR and the platform fee. `split[].fee` remains a merchant-supplied fee amount in major units.


## Key Concepts

1. **Split block** — Identifies which child merchants participate in the payment and the platform fee to deduct for each one.
2. **Item tagging** — Each line item in `items[]` must be tagged with a `merchant_id` so that the split is auditable and internally consistent.
3. **Validation** — The sum of item totals must reconcile to the charge total, and every merchant represented in the items must appear in `split[]`.
4. **Settlement** — For each merchant, Dime derives gross from tagged products, applies MDR to that gross, deducts the platform fee, and credits the remaining net amount. Payouts to bank accounts follow your settlement schedule.


## Endpoint

**POST** `/orders`

Include your standard Order payload plus the **Dime Bridge** fields shown below.

### Headers

- `client_key` (string, required)


### Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `lang` | string | Yes | Example: `en` |
| `data` | string (JWT) | Yes | Signed JWT containing your normal order fields **plus** the Dime Bridge fields below. |


### Dime Bridge Fields (add inside the JWT payload)

```jsonc
{
  // ... all your standard Order fields (currency, id, subtotal, total, email, items[], billingPerson, etc.)

  "split": [
    {
      "fee": 10,
      "merchant_id": "m4D8mQ1wMrdTUIg"
    },
    {
      "fee": 30,
      "merchant_id": "m7UarSiV9zWxN6v"
    }
  ]

  // IMPORTANT: each item in items[] must include a matching merchant_id
}
```

> **Items requirement:** each item must be tagged with `merchant_id` corresponding to one of the merchants in `split[]`.
**Charge reconciliation:** the sum of `items[].price * quantity` must equal the transaction charge total for bridge orders.


## Example Unsigned Payload (with Dime Bridge)

```json
{
  "webhookUrl": "https://webhookurl",
  "redirectUrl": "https://redirectUrl",
  "checkoutUrl": "https://checkoutUrl",
  "currency": "USD",
  "id": "ORDER-10001",
  "subtotal": 2000,
  "total": 2000,
  "email": "buyer@example.com",
  "items": [
    {
      "id": "SKU-BOOK-1",
      "name": "Hardcover Book",
      "price": 500,
      "quantity": 1,
      "merchant_id": "m4D8mQ1wMrdTUIg"
    },
    {
      "id": "SKU-COURSE-1",
      "name": "Online Course Access",
      "price": 1500,
      "quantity": 1,
      "merchant_id": "m7UarSiV9zWxN6v"
    }
  ],
  "split": [
    {
      "fee": 10,
      "merchant_id": "m4D8mQ1wMrdTUIg"
    },
    {
      "fee": 30,
      "merchant_id": "m7UarSiV9zWxN6v"
    }
  ]
}
```

### Signing the Payload

```javascript
const jwt = require('jsonwebtoken');
const payload = { /* the object above */ };
const signedData = jwt.sign(payload, 'your_secret_key');
```

### Final Request Body

```json
{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
```

### Response (201)

```json
{
  "order_url": "https://sandbox.dimepay.app/e-order/abcd1234"
}
```

## How It Works (Under the Hood)

1. **You post** the Order with `items[]` and the `split[]` block.
2. **We validate** that each item’s `merchant_id` maps to a merchant in `split[]`, that item totals equal the charge total, and that every split merchant has attributed items.
3. **At payment success**, Dime:
  - Derives each merchant’s **gross** portion from `items[]` grouped by `merchant_id`.
  - Calculates MDR and related processing deductions from that merchant gross.
  - Deducts the configured `split[].fee` amount.
  - Derives **merchant net** = `merchant_gross - MDR deductions - platform_fee`.
  - Credits merchant balances and records platform revenue.
4. **Webhooks** deliver the final breakdown so you can reconcile in your system.


> Exact fee and rounding behavior can be configured on your Dime account (currency precision, fee priority, min/max fees, etc.).


## Node.js Example — Build Split Merchant List from Items

This example shows how to:

- Tag items with `merchant_id`.
- Derive the `split[]` merchant list from grouped items.
- Apply per-merchant platform fees while letting Dime calculate merchant payouts.
- Sign and **create the Order**.


> Requires **axios** and **jsonwebtoken**.


```bash
npm install axios jsonwebtoken
```

```javascript
// bridge-order.js
const axios = require('axios');
const jwt = require('jsonwebtoken');

const API = 'https://sandbox.api.dimepay.app/dapi/v1';
const CLIENT_KEY = 'your_client_key';
const SIGNING_SECRET = 'your_secret_key';

// 1) Items (each must include merchant_id)
const items = [
  { id: 'SKU-BOOK-1', name: 'Hardcover Book', price: 500, quantity: 1, merchant_id: 'm4D8mQ1wMrdTUIg' },
  { id: 'SKU-COURSE-1', name: 'Online Course Access', price: 1500, quantity: 1, merchant_id: 'm7UarSiV9zWxN6v' }
];

// 2) Define platform fee per merchant
const feesByMerchant = {
  m4D8mQ1wMrdTUIg: 10,
  m7UarSiV9zWxN6v: 30
};

// 3) Build split[] by grouping items per merchant
function buildSplitFromItems(items, feesByMerchant) {
  const merchants = new Set();
  for (const it of items) {
    merchants.add(it.merchant_id);
  }
  const split = [];
  for (const merchant_id of merchants.values()) {
    split.push({
      merchant_id,
      fee: feesByMerchant[merchant_id] ?? 0
    });
  }
  return split;
}

async function createBridgeOrder() {
  const subtotal = items.reduce((s, it) => s + (it.price * it.quantity), 0);
  const total = subtotal; // add taxes/discounts as needed

  const split = buildSplitFromItems(items, feesByMerchant);

  const payload = {
    webhookUrl: 'https://webhookurl',
    redirectUrl: 'https://redirectUrl',
    checkoutUrl: 'https://checkoutUrl',
    currency: 'USD',
    id: 'ORDER-10001',
    subtotal,
    total,
    email: 'buyer@example.com',
    items,
    split
  };

  const data = jwt.sign(payload, SIGNING_SECRET);

  const res = await axios.post(`${API}/orders`, { lang: 'en', data }, {
    headers: { client_key: CLIENT_KEY }
  });

  console.log('Hosted Order URL:', res.data.order_url);
}

createBridgeOrder().catch(err => {
  console.error(err.response?.data || err.message);
});
```

## Troubleshooting & Tips

- **Validation errors**: Ensure every `items[].merchant_id` has a corresponding entry in `split[]`, and ensure the total of `items[].price * quantity` equals the charge total.
- **Decimals**: Use major currency units with up to 2 decimal places (e.g., USD). For more precision (e.g., JMD with no decimals), configure your account accordingly.
- **Deprecated field**: Do not send `split[].amount`. Dime ignores merchant-supplied split payout amounts and derives them from item totals.
- **Fees**: `split[].fee` is a platform fee amount deducted after MDR.
- **One-merchant carts**: You can still use Dime Bridge with a single merchant (it will act like a normal order with a per-merchant platform fee).


## Security

All requests require your API key header:

```http
client_key: <your_api_key>
```