> ## Documentation Index
> Fetch the complete documentation index at: https://docs-beta.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 objects">
  Invoice allocations allow specifying a payment to be for multiple invoices.
  Most commonly the full payment will be allocated to a single invoice, but any number of allocations are allowed.
  The sum of all allocations must be equal to the payment amount.

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

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

    <ResponseField name="amount" required="true" type="integer">
      Customer payment amount, in cents.
    </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": 90,
       "processor": "STRIPE",
       "imported_at": "2024-02-27T02:16:40.389772Z",
       "allocations": [
         {
           "invoice_id": "57f0fada-bb56-4f3e-9afa-2a222b68009e",
           "payment_id": "e67c216b-28f4-4a0e-9a21-7f05c19e4c66",
           "amount": 90,
           "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": {}
         }
       ],
        "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>