Participatory Finance
Seven products in which the return comes from the outcome of a real transaction or venture, not from an announced interest rate. A partnership pays out what the venture earned. An instalment sale earns a markup agreed once, at signing, that does not grow with time. A lease earns rent for the use of a thing the lessor actually owns.
They share one storage layer and one set of arithmetic, and they are available in two readings.
Two readings of the same contract
Each product has a secular reading and a religious reading. The contract, the money, the ledger postings and the schedules are identical — what differs is the vocabulary and the review requirement.
| Product | Secular endpoint (this section) | Religious reading |
|---|---|---|
| Partnerships | /api/v1/pfp/partnerships | Musharaka |
| Instalment sales | /api/v1/pfp/installment-sales | Murabaha |
| Leases | /api/v1/pfp/leases | Ijara |
| Managed investments | /api/v1/pfp/managed-investments | Mudaraba |
| Certificate issues | /api/v1/pfp/certificate-issues | Sukuk |
| Safekeeping deposits | /api/v1/pfp/safekeeping-deposits | Wadiah |
| Investment deposits | /api/v1/pfp/investment-deposits | Mudaraba deposit |
The religious reading lives at /api/v1/baas/islamic-banking/{product_type} and is available to platform operators and licensed banks, not to partners. It is described in Islamic Banking in the client documentation.
What actually differs between the readings:
| Secular | Religious | |
|---|---|---|
| Contract number prefix | PRT, INS, LSE, MIV, CRT, SFK, IVD | MSH, MRB, IJR, MUD, SKK, WDA, MUDD |
| Review | Optional. A contract can be funded without one | Mandatory. Funding is unreachable without a conclusion from the review board |
| Response shape | A curated field list; amounts as strings | The stored record with empty fields dropped; amounts as integers |
| Field names, arithmetic, schedules, ledger | Identical | Identical |
The field names are the same in both readings — compliance_review, markup_rate, custody_type — because both readings write the same columns. Religious vocabulary lives in the contract documents and in the operator's cabinet, not on the wire.
A contract created in one reading is not visible or mutable through the other. The two address families are isolated: requesting a secular contract at a religious address returns 404, and the reverse is also true.
Access
These endpoints require the Participatory Finance module to be activated for your organization by your platform operator.
If it is not, every endpoint in this section answers:
{
"error": "module_not_active",
"message": "Module 'participatory_finance' is not activated for this organization",
"details": { "module_id": "participatory_finance" }
}
with HTTP 403. Contact your platform operator to have it enabled.
Authentication
Same as the rest of the partner API — see Authentication.
curl https://4pay.online/api/v1/pfp/partnerships \
-H "x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Base URL: https://4pay.online/api/v1/pfp
Conventions
Money is integer minor units, sent as strings
Every monetary field is an integer number of minor units — kopecks, cents, fils — encoded as a JSON string.
{ "total_value": "150000000", "currency": "RUB" }
That is 1 500 000,00 RUB. Not 150 000 000 RUB, and not 1 500 000 RUB.
Two rules follow, and both bite in practice:
- Multiply by the currency's minor unit before sending. A user typing
1500into a form means 1 500 RUB, which is"150000"on the wire. Sending"1500"posts fifteen roubles. - Do not parse into a JavaScript number. A contract of 100 billion minor units exceeds
Number.MAX_SAFE_INTEGER, andparseFloatwill silently round it. Keep the string, or useBigInt.
Most amount fields must be strictly positive (^[1-9]\d*$). The exceptions are noted per endpoint: safekeeping accounts may be opened with a zero balance, and lease arrears accept zero to clear a delinquency.
Percentages are integers
| Field | Unit | Example |
|---|---|---|
profit_sharing_ratio | whole percent, the two parties must sum to 100 | {"bank": 60, "customer": 40} |
markup_rate | basis points | 1500 means 15 % |
expected_yield, indicative_rate | whole percent | 7 means 7 % |
bank_ownership_percent | whole percent, derived — not settable | 60 |
markup_rate is the one that catches people: it is in basis points, so 15 % is 1500, not 15.
The two parties are bank and customer
In every product the two sides of the contract are named bank and customer in the payload — the financing side and its counterparty. The names are historical and do not imply a banking licence: in a cooperative, bank is the fund and customer is the member.
Amounts in, amounts out
Responses return amounts as strings too, and null where a field was never set. A null amount means not specified; a "0" means specified and zero. The distinction matters for optional thresholds — a safekeeping account with "minimum_balance": null has no minimum, one with "minimum_balance": "0" has a minimum of zero.
Contract numbers
Every contract gets a contract_number on creation, in the form PREFIX-REGION-YYYYMMDD-XXXXXX:
PRT-P-RU-20260823-4A7F1C
The prefix encodes the product and its reading — PRT-P is a permanent partnership in the secular reading, MSH-P the same contract in the religious one. The region is the two-letter contract region, or XX if none was given. The last group is six random hexadecimal digits, not a counter: two contracts created the same day in the same region are distinguished by it, and a collision is rejected by a unique index rather than passing unnoticed.
The number is generated by the platform and cannot be set or changed.
Environment
Every endpoint accepts an optional env query parameter, test or prod. It defaults to prod. Test-environment contracts are stored separately and never post to the production ledger.
The shared lifecycle
Five of the seven products follow the same opening sequence:
draft ──submit──> under_review ──review──> review_passed ──> (funding) ──> active
│
└ ──reject──> rejected
draft— created, editable, nothing has moved.under_review— submitted for approval; the parties are agreeing terms.review_passed— a conclusion has been attached. Money can now move.rejected— a terminal state. Rejection requires areason.
After active, each product diverges: instalment sales complete or default, leases return or terminate, partnerships dissolve, certificate issues mature and redeem.
The two deposit products have no review stage — they start at pending and open with activate.
The review object
POST /{product}/{id}/review attaches the record of approval. It is stored on the contract as compliance_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. The other three fields are free. In the secular reading a review is optional — a contract may go from draft straight through funding without one — but if you attach a review, it must name who approved.
All five contract products also expose POST /{product}/{id}/reject, which takes a reason and is terminal. The two deposit products have neither.
Errors
The format is the platform standard — see Error Reference.
| Code | Meaning in this section |
|---|---|
400 | Malformed body, or unparseable amount |
403 | The participatory_finance module is not active for your organization |
404 | No contract with this ID in this reading — check you are not addressing a religious-reading contract |
422 | Validation failed. details names the field: contributions not summing to the total value, profit shares not summing to 100, a transition not allowed from the current status |
The details map carries the platform's own validation strings, and for this product family they are in Russian. They are meant for your logs and for support, not for display to an end user — map the field name, not the message, when you surface an error in your own interface.
A transition attempted from the wrong status returns 422 with the current status named:
{
"error": "unprocessable_entity",
"details": { "status": ["переход недоступен из стадии draft"] }
}
Where to go next
| Product | Use it when |
|---|---|
| Partnerships | Two sides put capital into a common venture and share what it earns |
| Instalment sales | A buyer needs an asset now and pays for it over time at a fixed markup |
| Leases | A user needs the use of an asset; the owner keeps title and the ownership costs |
| Managed investments | One side provides capital, the other provides the work |
| Certificate issues | Many holders fund one asset and share its income |
| Safekeeping deposits | A demand account with the principal guaranteed and no promised return |
| Investment deposits | A term deposit whose return depends on results, not on a rate |