> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk create loan payments > Creates or updates payments for a loan in a single atomic request. Items are upserted by `external_id`: payments matching an existing `external_id` are updated, all others are created. The response returns payments in request order. If any item is invalid, the entire batch is rejected. Items may omit `loan_id` and `loan_external_id`; if provided, they must match the loan in the request path. ## OpenAPI ````yaml post /v1/businesses/{businessId}/loans/{loanId}/payments/bulk openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/loans/{loanId}/payments/bulk: post: tags: [] summary: Bulk create loan payments description: >- Creates or updates payments for a loan in a single atomic request. Items are upserted by `external_id`: payments matching an existing `external_id` are updated, all others are created. The response returns payments in request order. If any item is invalid, the entire batch is rejected. Items may omit `loan_id` and `loan_external_id`; if provided, they must match the loan in the request path. operationId: business.loans.loanId.payments.bulk.post parameters: - name: businessId in: path description: The UUID of the business. required: true schema: type: string format: uuid - name: loanId in: path required: true description: The UUID of the loan. schema: type: string format: uuid requestBody: description: The loan payments to create or update. required: true content: application/json: schema: $ref: '#/components/schemas/BulkCreateLoanPaymentsParams' examples: bulk_payments: summary: Two payments created in one request value: payments: - external_id: loan-pmt-001 amount: 150000 date: '2024-02-15' splits: - split_type: PRINCIPAL amount: 120000 - split_type: INTEREST amount: 30000 method: ACH - external_id: loan-pmt-002 amount: 150000 date: '2024-03-15' splits: - split_type: PRINCIPAL amount: 121000 - split_type: INTEREST amount: 29000 method: ACH responses: '201': description: Loan payments created or updated successfully. content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ApiLoanPayment' components: schemas: BulkCreateLoanPaymentsParams: type: object required: - payments properties: payments: type: array minItems: 1 description: >- The payments to create or update. `external_id` values must be unique within the request. items: $ref: '#/components/schemas/CreateLoanPaymentParams' ApiLoanPayment: type: object description: >- A payment made against a loan, broken down into principal, interest, and fee splits. required: - id - business_id - loan_id - splits - amount - date - defer_posting - method - transaction_tags properties: id: type: string format: uuid description: Unique identifier for the loan payment. business_id: type: string format: uuid description: ID of the business that made the payment. external_id: type: string nullable: true description: Unique ID of the payment in your system for linking purposes. loan_id: type: string format: uuid description: ID of the loan this payment applies to. splits: type: array items: $ref: '#/components/schemas/ApiLoanPaymentSplit' description: The principal, interest, and fee splits that make up this payment. amount: type: integer format: int64 description: Total payment amount, in cents. date: type: string format: date description: Date of the payment. defer_posting: type: boolean description: Whether posting to the ledger is deferred. method: $ref: '#/components/schemas/PaymentMethod' processor: type: string nullable: true description: Payment processor, if any. payment_clearing_account: allOf: - $ref: '#/components/schemas/SingleApiChartAccount' nullable: true description: The clearing account used for the payment, if any. archived_at: type: string format: date-time nullable: true description: When the payment was archived, if applicable. memo: type: string nullable: true description: Internal note about the payment. metadata: type: object additionalProperties: true nullable: true description: >- Arbitrary JSON object you can attach for your own use. Layer stores and returns it unchanged. reference_number: type: string nullable: true description: Reference number for the payment. transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' description: Tags applied to this record. CreateLoanPaymentParams: type: object description: >- Parameters for recording a loan payment. Provide exactly one of `loan_id` or `loan_external_id` to identify the loan. required: - amount - date properties: loan_id: type: string format: uuid nullable: true description: ID of the loan being paid. Provide this or `loan_external_id`. loan_external_id: type: string nullable: true description: External ID of the loan being paid. Provide this or `loan_id`. external_id: type: string nullable: true description: Unique ID of the payment in your system for linking purposes. amount: type: integer format: int64 description: Total payment amount, in cents. Must equal the sum of the splits. date: type: string format: date description: Date of the payment. splits: type: array items: $ref: '#/components/schemas/CreateLoanPaymentSplitParams' nullable: true description: >- Breakdown of the payment into principal, interest, and fee portions. Optional for MCA and flex loans: when omitted, Layer derives a `PRINCIPAL`/`FEE` split from the loan's `fee_percentage` (`principal = amount / (1 + fee_percentage / 100)`, fee = remainder). Required for all other loan types. Provide explicit splits to override the derived ones. defer_posting: type: boolean default: false description: >- If true, the payment is recorded but not posted to the ledger until it is paid out or its due date is reached. method: allOf: - $ref: '#/components/schemas/PaymentMethod' default: OTHER description: Payment method. Defaults to `OTHER`. processor: type: string nullable: true description: Payment processor, if any (e.g. `stripe`). payment_clearing_account_identifier: allOf: - $ref: '#/components/schemas/AccountIdentifier' nullable: true description: >- Override the clearing account used for the payment. Defaults based on `method`. memo: type: string nullable: true description: Internal note about the payment. metadata: type: object additionalProperties: true nullable: true description: >- Arbitrary JSON object you can attach for your own use. Layer stores and returns it unchanged. reference_number: type: string nullable: true description: Reference number for the payment. ApiLoanPaymentSplit: type: object description: >- A split allocating part of a loan payment to principal, interest, or fee. required: - id - split_type - amount - account properties: id: type: string format: uuid description: Unique identifier for the split. external_id: type: string nullable: true description: Unique ID of the split in your system for linking purposes. split_type: $ref: '#/components/schemas/LoanPaymentSplitType' amount: type: integer format: int64 description: Split amount, in cents. account: allOf: - $ref: '#/components/schemas/AccountIdentifier' description: The ledger account this split posted to. PaymentMethod: type: string enum: - CASH - CHECK - CREDIT_CARD - ACH - CREDIT_BALANCE - OTHER example: ACH SingleApiChartAccount: type: object properties: type: type: string description: Resource type. Value will be `Single_Chart_Account`. example: Single_Chart_Account id: $ref: '#/components/schemas/AccountIdentifier' name: type: string description: Name of the account. example: Current Assets account_number: type: string nullable: true description: Account number if configured. example: '4000' stable_name: $ref: '#/components/schemas/AccountStableName' normality: $ref: '#/components/schemas/BankTransactionDirection' account_type: $ref: '#/components/schemas/ApiLedgerAccountType' account_subtype: $ref: '#/components/schemas/ApiLedgerAccountSubtype' description: A single ledger account without nested children. ApiTag: type: object properties: id: type: string format: uuid description: ID for the tag. key: type: string description: Key for the tag. example: ExampleTagKey dimension_display_name: type: string nullable: true description: Display name for the tag dimension. value: type: string description: Value for the tag. example: ExampleTagValue value_display_name: type: string nullable: true description: Display name for the tag value definition. dimension_id: type: string format: uuid description: ID of the tag dimension this tag belongs to. definition_id: type: string format: uuid description: ID of the tag value definition. archived_at: type: string format: date-time nullable: true description: When the tag was archived. required: - id - key - value - dimension_id - definition_id CreateLoanPaymentSplitParams: type: object description: >- How a portion of a loan payment is allocated. All splits on a payment must sum to the payment `amount`. required: - split_type - amount properties: split_type: $ref: '#/components/schemas/LoanPaymentSplitType' amount: type: integer format: int64 description: Split amount, in cents. account_identifier: allOf: - $ref: '#/components/schemas/AccountIdentifier' nullable: true description: >- For `INTEREST` and `FEE` splits, the expense account to post to (defaults to `INTEREST_EXPENSE` and `OTHER_FEES` respectively). Ignored for `PRINCIPAL` splits. external_id: type: string nullable: true description: Unique ID of the split in your system for linking purposes. AccountIdentifier: oneOf: - $ref: '#/components/schemas/AccountId' description: ID of the account. title: Account ID - $ref: '#/components/schemas/AccountStableName' description: Stable name associated with the account. title: Account Stable Name LoanPaymentSplitType: type: string description: The portion of a loan payment a split applies to. enum: - PRINCIPAL - INTEREST - FEE example: PRINCIPAL AccountStableName: type: object required: - type - stable_name properties: type: type: string enum: - StableName description: Resource type. Value will be `StableName`. example: StableName stable_name: type: string example: CURRENT_ASSETS description: Stable name of the account. BankTransactionDirection: type: string enum: - CREDIT - DEBIT example: DEBIT ApiLedgerAccountType: type: object properties: value: $ref: '#/components/schemas/LedgerAccountType' description: Type of the account. display_name: type: string description: Display name of the account type. example: Asset ApiLedgerAccountSubtype: type: object properties: value: $ref: '#/components/schemas/LedgerAccountSubtype' display_name: type: string description: Display name of the account subtype. example: Current Assets AccountId: type: object required: - type - id properties: type: type: string enum: - AccountId description: Resource type. Value will be `AccountId`. example: AccountId id: type: string format: uuid description: ID of the account. LedgerAccountType: type: string enum: - ASSET - LIABILITY - EQUITY - REVENUE - EXPENSE example: ASSET LedgerAccountSubtype: type: string enum: - BANK_ACCOUNTS - ACCOUNTS_RECEIVABLE - INVENTORY - PAYMENT_PROCESSOR_CLEARING_ACCOUNT - FIXED_ASSET - ACCUMULATED_DEPRECIATION - CASH - UNDEPOSITED_FUNDS - CURRENT_ASSET - NON_CURRENT_ASSET - PREPAID_EXPENSES - DEVELOPMENT_COSTS - LOANS_RECEIVABLE - INTANGIBLE_ASSET - ACCOUNTS_PAYABLE - CREDIT_CARD - TAXES_PAYABLE - INCOME_TAXES_PAYABLE - SALES_TAXES_PAYABLE - OTHER_TAXES_PAYABLE - PAYROLL_TAXES_PAYABLE - UNEARNED_REVENUE - PAYROLL_LIABILITY - PAYROLL_CLEARING - LINE_OF_CREDIT - TIPS - REFUND_LIABILITIES - UNDEPOSITED_OUTFLOWS - OUTGOING_PAYMENT_CLEARING_ACCOUNT - OTHER_CURRENT_LIABILITY - LOANS_PAYABLE - NOTES_PAYABLE - SHAREHOLDER_LOAN - NON_CURRENT_LIABILITY - CONTRIBUTIONS - DISTRIBUTIONS - COMMON_STOCK - PREFERRED_STOCK - ADDITIONAL_PAID_IN_CAPITAL - RETAINED_EARNINGS - ACCUMULATED_ADJUSTMENTS - OPENING_BALANCE_EQUITY - OTHER_EQUITY - SALES - UNCATEGORIZED_REVENUE - RETURNS_ALLOWANCES - DIVIDEND_INCOME - INTEREST_INCOME - OTHER_INCOME - COGS - OPERATING_EXPENSES - PAYROLL - TAXES_LICENSES - UNCATEGORIZED_EXPENSE - CHARITABLE_CONTRIBUTIONS - LOAN_EXPENSES - FINANCE_COSTS - INTEREST_EXPENSES - DEPRECIATION - AMORTIZATION - BAD_DEBT - OTHER_EXPENSES example: BANK_ACCOUNTS securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````