> ## 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.

# Invoice Payment object

Invoice payments represent payments made by customers of a business.
Payments may be made at any time and applied to any outstanding (sent, but not fully paid) invoice.

### Attributes

<ParamField body="id" required="true" type="string">
  Unique identifier for the payment.
</ParamField>

<ParamField body="external_id" type="string">
  Unique ID of the invoice payment in an external system for linking and
  idempotency.
</ParamField>

<ParamField body="at" required="true" type="string">
  Timestamp when the payment was completed.
</ParamField>

<ParamField body="method" required="true" type="enum">
  Payment method. Possible values are: `CASH`, `CHECK`, `CREDIT_CARD`, `ACH`,
  `CREDIT_BALANCE`, `OTHER`
</ParamField>

<ParamField body="fee" required="true" type="integer">
  Fee paid by business for processing of payment in positive cents.
</ParamField>

<ParamField body="additional_fees" type="array of InvoicePaymentFee objects">
  <Expandable title="InvoicePaymentFee properties">
    <ParamField body="description" type="string">
      Optional description of the fee.
    </ParamField>

    <ParamField body="account" required="true" type="object">
      The [Account Identifier](/api-reference/ledger/account-identifier) for the fee to be debited.
    </ParamField>

    <ParamField body="fee_amount" required="true" type="integer">
      Amount of the fee in cents.
    </ParamField>

    <ParamField body="is_passed_to_customer" required="true" type="boolean">
      Whether or not the fee is passed to the customer. It is paid by the business otherwise.
      When calculating the outstanding balance on the invoice, only the portion of each payment allocation that is applied to the invoice (excluding pass-through fees) is considered. This allows customers to pay the invoice amount plus any pass-through fees without the invoice being considered overpaid.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="amount" required="true" type="integer">
  Customer payment amount, in cents.
</ParamField>

<ParamField body="processor" type="string">
  Processor used to make the payment, if any.
  Any processor name can be provided and will be tracked.
</ParamField>

<ParamField body="imported_at" required="true" type="ISO8601 timestamp">
  Timestamp when the payment was imported into Layer.
</ParamField>

<ParamField body="dedicated_refunds" type="array of CreateDedicatedRefundParams objects">
  List of [Dedicated Refunds](/api-reference/refunds/refund#create-dedicated-refund-parameters-object) to create with this payment
</ParamField>

<ParamField body="tags" type="array of TagKeyValue objects">
  Tags to apply to the payment. Tags are key-value pairs that can be used to categorize and filter payments.

  <Expandable title="TagKeyValue properties">
    <ParamField body="key" required="true" type="string">
      The tag dimension key (e.g., "department", "project", "location")
    </ParamField>

    <ParamField body="dimension_display_name" type="string">
      Optional display name for the tag dimension. If not specified, `key` will be displayed.
    </ParamField>

    <ParamField body="value" required="true" type="string">
      The tag value (e.g., "engineering", "project-alpha", "san-francisco")
    </ParamField>

    <ParamField body="value_display_name" type="string">
      Optional display name for the tag value definition. If not specified, `value` will be displayed.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="allocations" required="true" type="array of InvoicePaymentAllocation and InvoicePaymentAllocationToLedgerAccount objects">
  Allocations specify how a payment is distributed. A payment can include two types of allocations:

  * **`InvoicePaymentAllocation`**: Allocates a portion of the payment to a specific invoice.
  * **`InvoicePaymentAllocationToLedgerAccount`**: Allocates a portion of the payment directly to a ledger account, rather than to an invoice. This is useful for recording payments that are not associated with a specific invoice, such as overpayments or deposits.

  A payment may contain any combination of invoice and ledger account allocations. The sum of all allocation amounts must be less than or equal to the payment amount.

  <Expandable title="InvoicePaymentAllocation properties">
    <ResponseField name="invoice_id" type="string">
      ID of an invoice to which this payment is applied.
    </ResponseField>

    <ResponseField name="payment_id" type="string">
      ID of the payment this allocation applies from.
    </ResponseField>

    <ResponseField name="amount" required="true" type="integer">
      Customer payment amount, in cents.
    </ResponseField>

    <ResponseField name="memo" type="string">
      Optional memo for the allocation.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary custom metadata in JSON format.
    </ResponseField>

    <ResponseField name="reference_number" type="string">
      User-visible identifier for the allocation.
    </ResponseField>

    <ResponseField name="transaction_tags" type="Array of Tags">
      <Expandable title="Tag properties">
        <ResponseField name="id" required="true" type="string">
          Unique identifier for the tag
        </ResponseField>

        <ResponseField name="key" required="true" type="string">
          The tag's key
        </ResponseField>

        <ResponseField name="value" required="true" type="string">
          The tag's value
        </ResponseField>

        <ResponseField name="dimension_display_name" type="string">
          Display name for the tag dimension
        </ResponseField>

        <ResponseField name="value_display_name" type="string">
          Display name for the tag value
        </ResponseField>

        <ResponseField name="dimension_id" required="true" type="string">
          ID of the tag dimension
        </ResponseField>

        <ResponseField name="definition_id" required="true" type="string">
          ID of the tag value definition
        </ResponseField>

        <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
          When the tag was created
        </ResponseField>

        <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
          When the tag was last updated
        </ResponseField>

        <ResponseField name="deleted_at" type="ISO8601 timestamp">
          When the tag was deleted
        </ResponseField>

        <ResponseField name="archived_at" type="ISO8601 timestamp">
          When the tag was archived
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="InvoicePaymentAllocationToLedgerAccount properties">
    <ResponseField name="account_id" type="string">
      ID of the ledger account to which this payment is allocated.
    </ResponseField>

    <ResponseField name="payment_id" type="string">
      ID of the payment this allocation applies from.
    </ResponseField>

    <ResponseField name="amount" required="true" type="integer">
      Customer payment amount, in cents.
    </ResponseField>

    <ResponseField name="amount_net_of_refunds" type="integer">
      Amount allocated after applying any refunds, in cents.
    </ResponseField>

    <ResponseField name="memo" type="string">
      Optional memo for the allocation.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary custom metadata in JSON format.
    </ResponseField>

    <ResponseField name="reference_number" type="string">
      User-visible identifier for the allocation.
    </ResponseField>

    <ResponseField name="transaction_tags" type="Array of Tags">
      <Expandable title="Tag properties">
        <ResponseField name="id" required="true" type="string">
          Unique identifier for the tag
        </ResponseField>

        <ResponseField name="key" required="true" type="string">
          The tag's key
        </ResponseField>

        <ResponseField name="value" required="true" type="string">
          The tag's value
        </ResponseField>

        <ResponseField name="dimension_display_name" type="string">
          Display name for the tag dimension
        </ResponseField>

        <ResponseField name="value_display_name" type="string">
          Display name for the tag value
        </ResponseField>

        <ResponseField name="dimension_id" required="true" type="string">
          ID of the tag dimension
        </ResponseField>

        <ResponseField name="definition_id" required="true" type="string">
          ID of the tag value definition
        </ResponseField>

        <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
          When the tag was created
        </ResponseField>

        <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
          When the tag was last updated
        </ResponseField>

        <ResponseField name="deleted_at" type="ISO8601 timestamp">
          When the tag was deleted
        </ResponseField>

        <ResponseField name="archived_at" type="ISO8601 timestamp">
          When the tag was archived
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

<ResponseField name="transaction_tags" type="Array of Tags">
  <Expandable title="Tag properties">
    <ResponseField name="id" required="true" type="string">
      Unique identifier for the tag
    </ResponseField>

    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="dimension_display_name" type="string">
      Display name for the tag dimension
    </ResponseField>

    <ResponseField name="value_display_name" type="string">
      Display name for the tag value
    </ResponseField>

    <ResponseField name="dimension_id" required="true" type="string">
      ID of the tag dimension
    </ResponseField>

    <ResponseField name="definition_id" required="true" type="string">
      ID of the tag value definition
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>

    <ResponseField name="archived_at" type="ISO8601 timestamp">
      When the tag was archived
    </ResponseField>
  </Expandable>
</ResponseField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the invoice payment (for example, to display to end users).
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary custom metadata in JSON format with a size limit of 1KB.
</ParamField>

<ParamField body="reference_number" type="string">
  Any (typically user-visible) identifier you would like to associate with the invoice payment. Can be used to filter when listing invoice payment.
</ParamField>

<ResponseExample>
  ```json Response theme={null}
   {
     "data": {
       "type": "Payment",
       "id": "e67c216b-28f4-4a0e-9a21-7f05c19e4c66",
       "external_id": "payment-1",
       "at": "2024-02-27T02:16:40.369432Z",
       "method": "CREDIT_CARD",
       "fee": 20,
       "amount": 190,
       "processor": "STRIPE",
       "imported_at": "2024-02-27T02:16:40.389772Z",
       "allocations": [
         {
           "type": "InvoicePaymentAllocation",
           "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
           "invoice_id": "57f0fada-bb56-4f3e-9afa-2a222b68009e",
           "payment_id": "e67c216b-28f4-4a0e-9a21-7f05c19e4c66",
           "amount": 90,
           "amount_net_of_refunds": 90,
           "memo": null,
           "metadata": {},
           "reference_number": null,
           "transaction_tags": [
              {
                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "key": "department",
                "value": "sales",
                "dimension_display_name": "Department",
                "value_display_name": "Sales Team",
                "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
                "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                "created_at": "2024-02-27T02:16:40.389772Z",
                "updated_at": "2024-02-27T02:16:40.389772Z",
                "deleted_at": null,
                "archived_at": null
              }
            ]
         },
         {
           "type": "InvoicePaymentAllocationToLedgerAccount",
           "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
           "account_id": "50448df3-6f86-445e-b48f-0e80153e5d42",
           "payment_id": "e67c216b-28f4-4a0e-9a21-7f05c19e4c66",
           "amount": 100,
           "amount_net_of_refunds": 100,
           "memo": "Customer deposit",
           "metadata": {},
           "reference_number": null,
           "transaction_tags": []
         }
       ],
        "transaction_tags": [
          {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "key": "department",
            "value": "sales",
            "dimension_display_name": "Department",
            "value_display_name": "Sales Team",
            "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
            "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "created_at": "2024-02-27T02:16:40.389772Z",
            "updated_at": "2024-02-27T02:16:40.389772Z",
            "deleted_at": null,
            "archived_at": null
          }
        ],
       "metadata": {}
     }
   }
  ```
</ResponseExample>

## Optional: Create refunds with the invoice payment

This field can be specified when creating an invoice and any of its invoice line items or invoice payments

<ParamField body="dedicated_refunds" type="array of CreateDedicatedRefundParams objects">
  List of [Dedicated Refunds](/api-reference/refunds/refund#create-dedicated-refund-parameters-object) to create with this payment
</ParamField>