Partnerships

Two sides put capital into a common venture, share the profit by agreement, and bear the loss strictly in proportion to what each contributed.

That last clause is the whole product. Profit is divided as the parties agreed; loss is divided by contribution share, and no agreement changes that. A contract in which one side is protected from loss at the other's expense stops being a participation and becomes a loan at interest wearing the word "partnership" — and it will be treated as one by every regulator that looks at it.

The API enforces the asymmetry: profit_sharing_ratio is yours to set, bank_ownership_percent is derived from the contributions and cannot be set at all.

Base path: /api/v1/pfp/partnerships · Religious reading: Musharaka

Two forms

`partnership_type`	What happens	Ends when
`permanent`	Both sides keep their shares for the life of the venture and split what it earns	The parties dissolve it
`diminishing`	One side buys out the other's share in scheduled units; ownership shifts across the term	The last unit is bought

diminishing is the shape used for co-ownership of a thing — property, equipment, a vehicle. The financing side's share shrinks with each buyout, and if the arrangement includes rent for the use of the co-owned asset, the rent falls with it: you pay for the part you do not yet own.

Choosing diminishing makes term_months required. The platform then derives the buyout units:

units_total       = term_months / period_length(buyout_schedule)
buyout_unit_value = floor(bank_contribution / units_total)

buyout_schedule may be monthly, quarterly, semi_annually or annually; omitted, it means monthly. Periods are 30 days, not calendar months.

Statuses

draft ──submit──> under_review ──review──> review_passed ──┐
  │                    │                                   │
  │                    └──reject──> rejected               │
  │                                                        │
  └────────────────── fund ────────────────────────────────┘
                        │
                        v
                     funded ──activate──> active
                                            │
                        ┌───────────────────┼──────────────┐
                        v                   v              v
               buyout_in_progress      dissolved       completed

Status	Meaning
`draft`	Created, nothing has moved
`under_review`	Submitted for approval
`review_passed`	A conclusion is attached
`rejected`	Terminal. Requires a `reason`
`funded`	Contributions are in; start and expected end dates are set
`active`	The venture is running; profit and loss can be recorded
`buyout_in_progress`	Diminishing form, units are being bought
`completed`	The last unit was bought out
`dissolved`	Ended early, by agreement or otherwise

In the secular reading fund is reachable from draft as well as from review_passed — a review is optional. In the religious reading only review_passed funds.

Create a partnership

POST /api/v1/pfp/partnerships

{
  "customer_id": "8f2a1c44-0b6e-4d51-9a3f-1c8e5b7d2a90",
  "region": "RU",
  "partnership_type": "diminishing",
  "currency": "RUB",
  "total_value": "500000000",
  "bank_contribution": "350000000",
  "customer_contribution": "150000000",
  "profit_sharing_ratio": { "bank": 60, "customer": 40 },
  "term_months": 60,
  "buyout_schedule": "quarterly",
  "rental_amount": "1200000",
  "asset_description": "Warehouse, 1 400 m², Kazan"
}

Field	Type	Required	Notes
`customer_id`	uuid	✅	The counterparty
`region`	string	✅	Contract region; must be one supported by the chart of accounts
`partnership_type`	enum	✅	`permanent` \| `diminishing`
`total_value`	string	✅	Minor units. Must equal the sum of the two contributions
`bank_contribution`	string	✅	Minor units
`customer_contribution`	string	✅	Minor units
`profit_sharing_ratio`	object	✅	`{"bank": n, "customer": m}`, whole percent, must sum to 100
`currency`	string	—	ISO 4217
`term_months`	integer	—	Required when `partnership_type` is `diminishing`
`buyout_schedule`	enum	—	`monthly` \| `quarterly` \| `semi_annually` \| `annually`
`rental_amount`	string	—	Minor units, per period, for the use of the co-owned asset
`asset_description`	string	—	Free text
`metadata`	object	—	Your own data, returned untouched

Two validations reject most first attempts:

bank_contribution + customer_contribution must equal total_value exactly. There is no rounding slack.
profit_sharing_ratio must sum to exactly 100.

Response — 201 Created, status: "draft", with bank_ownership_percent and customer_ownership_percent derived from the contributions:

{
  "data": {
    "id": "3b9c2f18-77a4-4e0d-8c15-6ad2f9e40b31",
    "contract_number": "PRT-D-RU-20260823-4A7F1C",
    "status": "draft",
    "partnership_type": "diminishing",
    "customer_id": "8f2a1c44-0b6e-4d51-9a3f-1c8e5b7d2a90",
    "region": "RU",
    "currency": "RUB",
    "total_value": "500000000",
    "bank_contribution": "350000000",
    "customer_contribution": "150000000",
    "bank_ownership_percent": 70,
    "customer_ownership_percent": 30,
    "profit_sharing_ratio": { "bank": 60, "customer": 40 },
    "units_total": 20,
    "buyout_unit_value": "17500000",
    "units_bought": 0,
    "buyout_history": [],
    "total_profit": "0",
    "total_loss": "0",
    "bank_profit_share": "0",
    "customer_profit_share": "0",
    "rental_amount": "1200000",
    "rental_paid_total": "0",
    "term_months": 60,
    "asset_description": "Warehouse, 1 400 m², Kazan",
    "compliance_review": null,
    "inserted_at": "2026-08-23T09:14:22Z"
  }
}

Note the two ratios in that response and how far apart they are. Contributions are 70/30; profit is 60/40. That is legitimate — the party doing the work may take a larger slice of profit than its capital share — but if the venture loses money, the loss falls 70/30, not 60/40.

List partnerships

GET /api/v1/pfp/partnerships

Query parameter	Values
`status`	any status above
`region`	contract region
`type`	`permanent` \| `diminishing`
`env`	`test` \| `prod` (default `prod`)

Returns the short form — identity, status, contributions, ownership percentages. Profit shares, the buyout history and the review are in the detail response only.

GET /api/v1/pfp/partnerships/{id}

Lifecycle transitions

Submit for approval

POST /api/v1/pfp/partnerships/{id}/submit

No body. draft → under_review.

Attach the approval

POST /api/v1/pfp/partnerships/{id}/review

{
  "approved_by": "Investment Committee, minutes 14/2026",
  "signed_at": "2026-08-01",
  "document_ref": "IC-2026-014",
  "note": "Approved subject to quarterly reporting"
}

approved_by is required and must not be blank. under_review → review_passed.

Reject

POST /api/v1/pfp/partnerships/{id}/reject

{ "reason": "Collateral valuation not supported" }

The reason is stored in metadata.rejection_reason. under_review → rejected, terminal.

Contributions are in

POST /api/v1/pfp/partnerships/{id}/fund

No body. Sets start_date to today and expected_end_date to term_months × 30 days out — 120 months if no term was given. For a diminishing partnership it also computes next_buyout_date.

Start work

POST /api/v1/pfp/partnerships/{id}/activate

No body. funded → active.

Profit and loss

Distribute profit

POST /api/v1/pfp/partnerships/{id}/profit

{
  "gross_profit": "8000000",
  "period_end_date": "2026-09-30"
}

The gross profit is split by profit_sharing_ratio, added to total_profit, bank_profit_share and customer_profit_share — and the counterparty's share is moved to it by a ledger posting, dated by period_end_date. This is not an accrual on paper: money leaves the venture's account.

period_end_date is required because the ledger posting is dated by it.

Rounding remainders go to the counterparty, not to the financing side. Over many distributions the alternative would quietly accumulate kopecks on one side.

Record a loss

POST /api/v1/pfp/partnerships/{id}/loss

{ "amount": "3000000" }

Divided by contribution share, not by the profit ratio. With contributions of 70/30 as above, a loss of 3 000 000 splits 2 100 000 / 900 000 — regardless of the 60/40 profit agreement.

The split is recorded in metadata.last_loss and accumulated in total_loss:

{
  "last_loss": {
    "amount": "3000000",
    "bank_share": "2100000",
    "customer_share": "900000",
    "date": "2026-09-30"
  }
}

Buyout (diminishing form only)

POST /api/v1/pfp/partnerships/{id}/buyout

{ "units": 1 }

units defaults to 1. Each unit moves buyout_unit_value from the financing side to the counterparty and recomputes both ownership percentages:

customer_percent = floor((customer_contribution + buyout_unit_value × units_bought) × 100 / total_value)
bank_percent     = 100 − customer_percent

The counterparty's own initial contribution is part of the sum, so ownership moves forward from where it already stood. In the example above the member starts at 30 % and reaches 33 % after the first of twenty units.

Each call appends to buyout_history, scales the rent down in proportion to the share still owned by the financing side, and moves the contract to completed once the last unit is bought — at which point the counterparty holds 100 %.

Called on a permanent partnership it returns 422 — buyout exists only in the diminishing form.

Because the ownership percentages move, the loss split moves with them. A loss recorded after half the units have been bought divides differently from one recorded on day one. That is the intended behaviour: loss follows ownership as it stands at the time.

Dissolve

POST /api/v1/pfp/partnerships/{id}/dissolve

{ "reason": "Parties agreed to wind up the venture" }

Ends the contract early. Terminal.

Worked example

A cooperative fund and a member co-buy a warehouse for 5 000 000 RUB. The fund puts in 3 500 000, the member 1 500 000. They agree the member, who will run the warehouse, takes 40 % of profit. The member buys out the fund quarterly over five years.

# 1. Create — amounts in kopecks
curl -X POST https://4pay.online/api/v1/pfp/partnerships \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8f2a1c44-0b6e-4d51-9a3f-1c8e5b7d2a90",
    "region": "RU", "partnership_type": "diminishing", "currency": "RUB",
    "total_value": "500000000",
    "bank_contribution": "350000000",
    "customer_contribution": "150000000",
    "profit_sharing_ratio": {"bank": 60, "customer": 40},
    "term_months": 60, "buyout_schedule": "quarterly",
    "rental_amount": "1200000"
  }'

# 2. Contributions are in, work starts
curl -X POST .../partnerships/$ID/fund -H "x-api-key: $KEY" -d '{}'
curl -X POST .../partnerships/$ID/activate -H "x-api-key: $KEY" -d '{}'

# 3. First quarter earned 80 000 RUB
curl -X POST .../partnerships/$ID/profit -H "x-api-key: $KEY" \
  -d '{"gross_profit": "8000000", "period_end_date": "2026-11-30"}'
# fund 48 000 RUB, member 32 000 RUB — by the 60/40 agreement

# 4. First buyout unit
curl -X POST .../partnerships/$ID/buyout -H "x-api-key: $KEY" \
  -d '{"units": 1}'
# 175 000 RUB of ownership moves: the member goes from 30 % to 33 %,
# and the rent falls because less of the warehouse is rented
# (ownership percentages are whole numbers, rounded down)

If instead the quarter had lost 80 000 RUB, the split would be 56 000 / 24 000 — by the 70/30 contributions, not by the 60/40 agreement.

Partnerships

Two forms​

Statuses​

Create a partnership​

List partnerships​

Lifecycle transitions​

Submit for approval​

Attach the approval​

Reject​

Contributions are in​

Start work​

Profit and loss​

Distribute profit​

Record a loss​

Buyout (diminishing form only)​

Dissolve​

Worked example​