Update loan application requirement

Your lender configuration controls two lists of documents that shape the loan application:

  • Supporting documents: files the merchant uploads for your underwriting review.
  • Agreement documents: files you provide, such as your financing agreement or terms and conditions, that the merchant reads before applying.

You update both with one request to PUT /v1/capitals/lenders/configs. Both fields are required, and each list you send replaces the stored list in full.

Supporting documents

When a merchant submits a loan application, PayMongo prompts them to upload supporting documents. By default, accounts are asked to provide the following documents:

TypeDescription
dti_registrationDTI Business Name Registration certificate
sec_registrationSEC Certificate of Incorporation
sec_certificateNotarized Secretary's Certificate
articles_of_incorporationArticles of Incorporation
latest_gisLatest General Information Sheet (GIS)
government_idGovernment ID

You can tailor this list to match your underwriting policy. Set required: true to make a document mandatory, or required: false to make it optional. Only the document types listed in the request body are kept; omitted types are removed.

Agreement documents

You can attach up to 10 agreement documents. Each one is a file you upload to the Files API, plus a title shown to merchants.

  1. Upload each agreement file to the Files API with purpose: capital_agreement_document. The file must belong to your lender account.
  2. Add the file IDs to agreement_documents on your lender configuration.
  3. When a merchant opens an offer and proceeds to the application Review Detail screen, they see each document as a titled link that opens in a new tab.

You can also manage agreement documents without the API, from Dashboard → Capital → Lender → Configurations, in the Agreement documents section. There you can upload files up to 24 MB, and reorder, retitle, replace, or remove documents. Saving the section submits the full current list.

FieldTypeRequiredDescription
typestringYesMust be "file". The link value is reserved for future use.
titlestringYesDisplay name shown to merchants. 1–100 characters.
file_idstringYesID of a file you uploaded to the Files API with purpose: capital_agreement_document. Must be unique within the list.

Documents are stored and shown to merchants in the order you send them.

Update your configuration

curl -X PUT https://api.paymongo.com/v1/capitals/lenders/configs \
  -u sk_live_your_key: \
  -H "Content-Type: application/json" \
  -d '{
    "supporting_documents": [
      { "document_type": "dti_registration", "required": true },
      { "document_type": "government_id", "required": false }
    ],
    "agreement_documents": [
      { "type": "file", "title": "Loan Agreement", "file_id": "file_a1b2c3d4e5f6" },
      { "type": "file", "title": "Terms and Conditions", "file_id": "file_f6e5d4c3b2a1" }
    ]
  }'

Send an empty array ([]) to clear either list. Omitting either field returns 422.

The endpoint returns 200 with the updated lender configuration in data:

{
  "data": {
    "lender_id": "org_01HX...",
    "supporting_documents": [
      { "document_type": "dti_registration", "required": true },
      { "document_type": "government_id", "required": false }
    ],
    "agreement_documents": [
      {
        "type": "file",
        "title": "Loan Agreement",
        "file_id": "file_a1b2c3d4e5f6",
        "url": "https://files.example.com/presigned/file_a1b2c3d4e5f6"
      },
      {
        "type": "file",
        "title": "Terms and Conditions",
        "file_id": "file_f6e5d4c3b2a1",
        "url": null
      }
    ],
    "offer_notification_template_id": "",
    "status": "active"
  }
}

Each agreement document in the response includes a url: a download link valid for 60 minutes. The link is generated on every read and never stored. If the link could not be generated at that moment, url is null; the document is still stored, and the next read tries again. Merchants see a document with a null URL as plain text instead of a link.

Changes take effect immediately for any applications submitted after the update.

Errors

The request is rejected and nothing is saved when:

HTTP statusCause
422supporting_documents or agreement_documents is missing.
422agreement_documents has more than 10 entries, a duplicate file_id, a type other than "file", or a title outside 1–100 characters.
422A file_id was not found for your lender account, or belongs to another account.
422A file's purpose is not capital_agreement_document.
500The Files API returned an unexpected error.
{
  "errors": [
    {
      "code": "invalid_request_body",
      "detail": "agreement_documents file_id was not found for this lender"
    }
  ]
}

Test and live mode

Configuration is partitioned by livemode. A request made with your test API key reads and writes your test-mode configuration; a request made with your live API key reads and writes your live-mode configuration. The two modes are independent, so set up your supporting and agreement documents in each mode separately. Files uploaded in test mode are not available in live mode, and the reverse.


Did this page help you?