Contract and Loan
How to retrieve and track your lender contracts and their associated loans using the PayMongo Capital API.
Contract
A Contract represents the credit facility agreement between your lending institution and an account.
| Field | Type | Description |
|---|---|---|
id | string | Unique contract identifier. |
status | string | active — contract is open and loans can be disbursed. completed — all loans are fully repaid and no further disbursements are allowed. |
currency | string | Currency of the contract (e.g., PHP). |
loan_type | string | revolving — repaid principal is returned to the available credit pool. term — single disbursement for the full approved amount. |
approved_amount | integer | Total credit limit approved under this contract, in the smallest currency unit (e.g., centavos for PHP). |
remaining_amount | integer | Credit still available for disbursement. For revolving contracts, this increases as the merchant repays. |
interest_fee | integer | Interest charged on each loan disbursement, expressed in the unit indicated by interest_fee_type. |
interest_fee_type | string | Unit for interest_fee. bps means basis points (100 bps = 1%). |
repayment_rate | integer | Daily repayment rate applied to the merchant's settled sales, expressed in the unit indicated by repayment_rate_type. |
repayment_rate_type | string | Unit for repayment_rate. bps means basis points. |
processing_fee | integer | Fee withheld from each disbursement under this contract. Copied from the offer when the application is submitted, so later edits to the offer do not change it. 0 when no processing fee applies. |
processing_fee_type | string | Unit for processing_fee. bps means basis points; fixed means a centavo amount. |
term | integer | Duration of the contract expressed in term_type units. |
term_type | string | Unit for term. E.g., month. |
created_at | string | ISO 8601 timestamp of when the contract was created. |
loans | array | Loans disbursed under this contract. See Loan fields below. |
Loans
Each object in the loans represents a single disbursement under the contract.
| Field | Type | Description |
|---|---|---|
id | string | Unique loan identifier. |
status | string | Current loan status. pending — disbursement transfer initiated, awaiting confirmation. active — disbursement confirmed; repayment collection has started. failed — disbursement failed; no funds were transferred and no repayments are collected. repaid — all outstanding principal, interest, and DST have been collected. |
purpose | string | Merchant-provided reason for the loan. |
principal_amount | integer | Approved principal in the smallest currency unit. This is the gross amount before any fee is deducted. |
processing_fee_amount | integer | Fee withheld at disbursement, in centavos. Computed from the contract's processing_fee and processing_fee_type: principal_amount × processing_fee / 10000 rounded down for bps, or the flat amount for fixed. Charged once per loan, including each revolving withdrawal. 0 when no processing fee applies. |
net_disbursement_amount | integer | Amount actually transferred to the merchant's wallet (principal_amount − processing_fee_amount). |
outstanding_principal_amount | integer | Remaining principal balance not yet collected. |
outstanding_interest_amount | integer | Remaining interest not yet collected. |
outstanding_dst_amount | integer | Remaining Documentary Stamp Tax (DST) not yet collected. |
created_at | string | ISO 8601 timestamp of when the loan was disbursed. |
Loan disbursement lifecycle
When a lender approves an application, or a merchant makes a withdrawal on a revolving contract, PayMongo creates the loan in pending status and initiates a disbursement transfer. The loan status progresses as follows:
| Status | Meaning | Repayment collected? |
|---|---|---|
pending | Transfer initiated; awaiting confirmation from the payments workflow. | No |
active | Transfer confirmed; funds are in the merchant's wallet and the repayment clock has started. | Yes |
failed | Transfer failed; no funds reached the merchant. | No |
repaid | All outstanding principal, interest, and DST have been collected. | — |
The loan's principal is deducted from the contract's remaining_amount when the loan is created. A failed loan keeps that principal reserved: remaining_amount is not restored, so the amount is not available for new loans. PayMongo operations can retry a failed disbursement. A retry moves the loan back to pending, and to active once the transfer succeeds.
Manual and direct lender repayments return
422for loans that are not inactivestatus, and the daily sales sweep skips them. See Repayment for the exact error details.
View Contracts and Loans via Lender Dashboard

- Open
Contractstab on Lender Dashboard. - Click
Viewbutton on selected contract.
View Contracts and Loans via API
curl https://api.paymongo.com/v1/capitals/lenders/contractsReturns all contracts for the authenticated lender, including each contract's associated loans.
Query parameters
| Parameter | Type | Description |
|---|---|---|
after | string | Cursor for forward pagination. |
limit | integer | Number of contracts to return per page. Min: 1, max: 50, default: 10. |
status | string | Filter by contract status. Accepted values: active, completed. |
Example: filter for active contracts
curl "https://api.paymongo.com/v1/capitals/lenders/contracts?status=active&limit=20"Example response
{
"data": [
{
"id": "contract_123",
"status": "active",
"currency": "PHP",
"loan_type": "revolving",
"approved_amount": 1000000,
"remaining_amount": 400000,
"interest_fee": 250,
"interest_fee_type": "bps",
"repayment_rate": 1250,
"repayment_rate_type": "bps",
"processing_fee": 300,
"processing_fee_type": "bps",
"term": 12,
"term_type": "month",
"loans": [
{
"id": "loan_123",
"status": "active",
"purpose": "Expand business inventory",
"principal_amount": 300000,
"processing_fee_amount": 9000,
"net_disbursement_amount": 291000,
"outstanding_principal_amount": 300000,
"outstanding_interest_amount": 15000,
"outstanding_dst_amount": 500,
"created_at": "2024-01-01T00:00:00Z"
}
]
}
]
}Pagination
The contracts list uses cursor-based pagination. To retrieve subsequent pages, pass the next value from metadata in the current response as the after parameter.
# First page
curl "https://api.paymongo.com/v1/capitals/lenders/contracts?limit=10"
# Next page — pass the "next" from metadata of the previous response
curl "https://api.paymongo.com/v1/capitals/lenders/contracts?limit=10&after=aGFpCg"Disbursement amount
When a loan is disbursed, the merchant's wallet receives net_disbursement_amount, not the full principal_amount. If no processing fee applies, these two values are equal.
net_disbursement_amount = principal_amount − processing_fee_amount
The withheld fee stays in your lender wallet — only net_disbursement_amount is transferred, so your wallet needs to cover the net amount, not the full principal. The disbursement transfer's amount is the net amount, and when a fee applies its notes record the withheld fee. Use net_disbursement_amount when reconciling wallet credits against loan records.
The fee must be less than the principal. The check runs when a loan is created — at approval for term loans, and at each withdrawal for revolving contracts — and returns 422 with processing fee must be less than the principal amount otherwise.
Tracking outstanding balances
The total amount still owed on a loan is the sum of its three outstanding components:
total_outstanding = outstanding_principal_amount
+ outstanding_interest_amount
+ outstanding_dst_amount
When all three reach zero, the loan transitions to repaid. When all loans under a contract are repaid and no further disbursements are made, the contract transitions to completed.
Updated 18 days ago
