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.

FieldTypeDescription
idstringUnique contract identifier.
statusstringactive — contract is open and loans can be disbursed. completed — all loans are fully repaid and no further disbursements are allowed.
currencystringCurrency of the contract (e.g., PHP).
loan_typestringrevolving — repaid principal is returned to the available credit pool. term — single disbursement for the full approved amount.
approved_amountintegerTotal credit limit approved under this contract, in the smallest currency unit (e.g., centavos for PHP).
remaining_amountintegerCredit still available for disbursement. For revolving contracts, this increases as the merchant repays.
interest_feeintegerInterest charged on each loan disbursement, expressed in the unit indicated by interest_fee_type.
interest_fee_typestringUnit for interest_fee. bps means basis points (100 bps = 1%).
repayment_rateintegerDaily repayment rate applied to the merchant's settled sales, expressed in the unit indicated by repayment_rate_type.
repayment_rate_typestringUnit for repayment_rate. bps means basis points.
processing_feeintegerFee 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_typestringUnit for processing_fee. bps means basis points; fixed means a centavo amount.
termintegerDuration of the contract expressed in term_type units.
term_typestringUnit for term. E.g., month.
created_atstringISO 8601 timestamp of when the contract was created.
loansarrayLoans disbursed under this contract. See Loan fields below.

Loans

Each object in the loans represents a single disbursement under the contract.

FieldTypeDescription
idstringUnique loan identifier.
statusstringCurrent 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.
purposestringMerchant-provided reason for the loan.
principal_amountintegerApproved principal in the smallest currency unit. This is the gross amount before any fee is deducted.
processing_fee_amountintegerFee 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_amountintegerAmount actually transferred to the merchant's wallet (principal_amount − processing_fee_amount).
outstanding_principal_amountintegerRemaining principal balance not yet collected.
outstanding_interest_amountintegerRemaining interest not yet collected.
outstanding_dst_amountintegerRemaining Documentary Stamp Tax (DST) not yet collected.
created_atstringISO 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:

StatusMeaningRepayment collected?
pendingTransfer initiated; awaiting confirmation from the payments workflow.No
activeTransfer confirmed; funds are in the merchant's wallet and the repayment clock has started.Yes
failedTransfer failed; no funds reached the merchant.No
repaidAll 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 422 for loans that are not in active status, and the daily sales sweep skips them. See Repayment for the exact error details.

View Contracts and Loans via Lender Dashboard

  1. Open Contracts tab on Lender Dashboard.
  2. Click View button on selected contract.

View Contracts and Loans via API

curl https://api.paymongo.com/v1/capitals/lenders/contracts

Returns all contracts for the authenticated lender, including each contract's associated loans.

Query parameters

ParameterTypeDescription
afterstringCursor for forward pagination.
limitintegerNumber of contracts to return per page. Min: 1, max: 50, default: 10.
statusstringFilter 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.


Did this page help you?