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

# Record a Payment

> This endpoint records a payment made towards an invoice in Layer.

### Path Parameters

<ParamField path="business_id" required="true" type="string">
  ID of the [Business](/api-reference/business/business) the invoice is
  associated with.
</ParamField>

### Body

<ParamField body="external_id" type="string">
  External ID for the payment within your platform. **Idempotency key.**
</ParamField>

<ParamField body="paid_at" required="true" type="ISO8601 timestamp">
  Date of the payment.
</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.
    </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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="amount" required="true" type="integer">
  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="payment_clearing_account_identifier" type="AccountIdentifier">
  The ledger account to use for the payment (overrides the default determined by the payment method).
</ParamField>

<ParamField body="invoice_payments" type="array of InvoicePaymentAllocation objects" required="true">
  <Expandable title="InvoicePaymentAllocation properties">
    <ResponseField name="invoice_id" type="uuid">
      Layer ID of the invoice to apply payment. Either the invoice\_id or invoice\_external\_id must be provided.
    </ResponseField>

    <ResponseField name="invoice_external_id" type="string">
      External ID of the invoice payment. Either the invoice\_id or invoice\_external\_id must be provided.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Amount paid towards this invoice in cents. Cannot exceed the amount of the
      associated payment.
    </ResponseField>

    <ResponseField name="tags" type="array of TagKeyValue objects">
      <Expandable title="TagKeyValue properties">
        <ResponseField name="key" required="true" type="string">
          The tag dimension key (e.g., "department", "project", "location")
        </ResponseField>

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

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

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

<ParamField body="dedicated_refunds" type="array of RefundAllocation objects">
  List of [Refund Allocations](/api-reference/refunds/refund#refund-allocation-object) associated with this invoice payment.
</ParamField>

<ResponseField name="tags" type="array of TagKeyValue objects">
  <Expandable title="TagKeyValue properties">
    <ResponseField name="key" required="true" type="string">
      The tag dimension key (e.g., "department", "project", "location")
    </ResponseField>

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

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

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

### Response

Returns the created [Invoice Payment Object](/api-reference/invoice/payments)

<RequestExample>
  ```bash Request theme={null}
  curl -X POST https://sandbox.layerfi.com/v1/businesses/{business_id}/invoices/payments \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "external_id": "payment-1",
      "paid_at": "2024-02-27T02:22:55.163005Z",
      "method": "CREDIT_CARD",
      "fee": 20,
      "amount": 90,
      "processor": "STRIPE",
      "invoice_payments": [
        {
          "invoice_id": "3a9c378e-dc02-4700-9158-f629d632a83b",
          "amount": 90,
          "tags": [
            {
              "key": "payment-source",
              "dimension_display_name": "Payment Source",
              "value": "online-portal",
              "value_display_name": "Online Portal"
            }
          ]
        }
      ],
      "additional_fees": [
        {
          "account": {
            "type": "StableName",
            "stable_name": "MERCHANT_CASH_ADVANCE"
          },
          "description": "MCA Fee",
          "fee_amount": 2
        }
      ],
      "tags": [
        {
          "key": "payment-channel",
          "dimension_display_name": "Payment Channel",
          "value": "in-store",
          "value_display_name": "In Store"
        },
        {
          "key": "department",
          "value": "sales"
        }
      ]
    }'
  ```
</RequestExample>

<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
            }
          ]
        }
      ],
      "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
        }
      ],
      "additional_fees": [
        {
          "account": {
            "type": "AccountId",
            "id": "50448df3-6f86-445e-b48f-0e80153e5d42"
          },
          "description": "MCA Fee",
          "fee_amount": 2
        }
      ],
    },
    "meta": {}
  }
  ```
</ResponseExample>