Send Money from Orders (Experimental)

About this feature

You can define the payout as a fixed amount or as a percentage of what remains after Ecart Pay fees are deducted from the order.

Automatic Transfers: Attach a payout object to an order at creation time; the transfer is triggered automatically once the order is paid.
Fixed or Percentage Amounts: Use percent: true to send a share of the post-fee balance, or omit it (or set percent: false) to send a fixed amount.
Fee-Aware Calculations: Payouts are always calculated from the merchant’s net balance after fees — not from the order total paid by the customer.
Built-in Protection: If the requested amount exceeds the available post-fee balance, the payout is automatically adjusted down to the maximum available.

Configure a Payout on Order Creation

Include a payout object in the body when creating an order. After the order is paid, Ecart Pay creates and processes the payout to the recipient’s account.

Endpoint

POST {{baseURL}}/api/orders

Headers

Authorization: {token}

Payout Object

Field	Type	Required	Description
`email`	string	Yes	Email of the recipient merchant. Must be different from the order creator’s account email.
`amount`	number	Yes	Payout value. Interpreted as a fixed currency amount or a percentage depending on `percent`. Must be greater than `0` when provided.
`percent`	boolean	No	When `true`, `amount` is treated as a percentage of the post-fee balance. When `false` or omitted, `amount` is a fixed amount. Defaults to `false`.

How the Payout Amount Is Calculated

When the order is paid, Ecart Pay deducts processing fees from the order total. The remaining balance (transaction.amount) is the maximum amount available for the payout.

Mode	`percent` value	Calculation
Fixed amount	`false` or omitted	`payout.amount`, capped at the post-fee balance
Percentage	`true`	`post-fee balance × (amount / 100)`

⚠️
IMPORTANT
The post-fee balance is only known at payment time. If a fixed amount exceeds that balance, the payout is automatically capped to the available amount.

Example Request — Fixed Amount

curl --location 'https://sandbox.ecartpay.com/api/orders' \
--header 'Authorization: {token}' \
--header 'Content-Type: application/json' \
--data '{
    "customer_id": "65c41df54ec03a5080230789",
    "currency": "MXN",
    "items": [
        {
            "code": "123",
            "name": "Brazalete religioso plateado BR3017",
            "quantity": 1,
            "price": 1000
        }
    ],
    "notify_url": "",
    "payout": {
        "email": "[email protected]",
        "amount": 1000,
        "percent": false
    }
}'

Result: Order total 1,000.00 MXN, fee 37.82 MXN, available 962.18 MXN → payout capped to 962.18 MXN.

Example Request — Percentage

curl --location 'https://sandbox.ecartpay.com/api/orders' \
--header 'Authorization: {token}' \
--header 'Content-Type: application/json' \
--data '{
    "customer_id": "65c41df54ec03a5080230789",
    "currency": "MXN",
    "items": [
        {
            "code": "123",
            "name": "Brazalete religioso plateado BR3017",
            "quantity": 1,
            "price": 1000
        }
    ],
    "notify_url": "",
    "payout": {
        "email": "[email protected]",
        "amount": 1,
        "percent": true
    }
}'

Result: 1% of 962.18 MXN → payout of 9.62 MXN.

Example Request — Full Balance (100%)

curl --location 'https://sandbox.ecartpay.com/api/orders' \
--header 'Authorization: {token}' \
--header 'Content-Type: application/json' \
--data '{
    "customer_id": "65c41df54ec03a5080230789",
    "currency": "MXN",
    "items": [
        {
            "code": "123",
            "name": "Brazalete religioso plateado BR3017",
            "quantity": 1,
            "price": 1000
        }
    ],
    "notify_url": "",
    "payout": {
        "email": "[email protected]",
        "amount": 100,
        "percent": true
    }
}'

Result: 100% of 962.18 MXN → payout of 962.18 MXN.

Example Response

{
    "id": "6a0b3c3ed7426e69cf4dbfa9",
    "number": "OR0000057966",
    "status": "paid",
    "currency": "MXN",
    "totals": {
        "subtotal": 1000,
        "total": 1000
    },
    "payout": {
        "email": "[email protected]",
        "amount": 100,
        "percent": true,
        "_id": "6a0b3c58d7426e69cf4dc006"
    }
}

Behavior Without a Payout

If the payout object is omitted from the order, no automatic transfer is created. Existing order flows are unchanged.

By configuring Send Money from Orders, businesses can split revenue with partners, suppliers, or affiliates at payment time — using fixed amounts or percentages — without managing payouts manually.