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

id · string · required

Unique identifier for the payment.

external_id · string

Unique ID of the invoice payment in an external system for linking and idempotency.

customer · object

The customer associated with this payment, if one has been set. You can tag a payment with a customer before it is allocated to any invoice (for example, a standalone deposit). Once the payment has invoice allocations, the customer must match the customer on every allocated invoice.

at · string · required

Timestamp when the payment was completed.

method · enum · required

Payment method. Possible values are: CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHER

fee · integer · required

Fee paid by business for processing of payment in positive cents.

additional_fees · array of InvoicePaymentFee objects

Show InvoicePaymentFee properties

description · string

Optional description of the fee.

account · object · required

The Account Identifier for the fee to be debited.

fee_amount · integer · required

Amount of the fee in cents.

is_passed_to_customer · boolean · required

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.

amount · integer · required

Customer payment amount, in cents.

processor · string

Processor used to make the payment, if any. Any processor name can be provided and will be tracked. Allowed only when method is CREDIT_CARD, ACH, CREDIT_BALANCE, or OTHER.

imported_at · ISO8601 timestamp · required

Timestamp when the payment was imported into Layer.

dedicated_refunds · array of CreateDedicatedRefundParams objects

List of Dedicated Refunds to create with this payment

tags · array of TagKeyValue objects

Tags to apply to the payment. Tags are key-value pairs that can be used to categorize and filter payments.

Show TagKeyValue properties

key · string · required

The tag dimension key (e.g., “department”, “project”, “location”)

dimension_display_name · string

Optional display name for the tag dimension. If not specified, key will be displayed.

value · string · required

The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)

value_display_name · string

Optional display name for the tag value definition. If not specified, value will be displayed.

allocations · array of InvoicePaymentAllocation and InvoicePaymentAllocationToLedgerAccount objects · required

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.

Show InvoicePaymentAllocation properties

invoice_id · string

ID of an invoice to which this payment is applied.

payment_id · string

ID of the payment this allocation applies from.

amount · integer · required

Customer payment amount, in cents.

memo · string

Optional memo for the allocation.

metadata · object

Arbitrary custom metadata in JSON format.

reference_number · string

User-visible identifier for the allocation.

transaction_tags · Array of Tags

Show Tag properties

id · string · required

Unique identifier for the tag

key · string · required

The tag’s key

value · string · required

The tag’s value

dimension_display_name · string

Display name for the tag dimension

value_display_name · string

Display name for the tag value

dimension_id · string · required

ID of the tag dimension

definition_id · string · required

ID of the tag value definition

created_at · ISO8601 timestamp · required

When the tag was created

updated_at · ISO8601 timestamp · required

When the tag was last updated

deleted_at · ISO8601 timestamp

When the tag was deleted

archived_at · ISO8601 timestamp

When the tag was archived

Show InvoicePaymentAllocationToLedgerAccount properties

account_id · string

ID of the ledger account to which this payment is allocated.

payment_id · string

ID of the payment this allocation applies from.

amount · integer · required

Customer payment amount, in cents.

amount_net_of_refunds · integer

Amount allocated after applying any refunds, in cents.

memo · string

Optional memo for the allocation.

metadata · object

Arbitrary custom metadata in JSON format.

reference_number · string

User-visible identifier for the allocation.

transaction_tags · Array of Tags

Show Tag properties

id · string · required

Unique identifier for the tag

key · string · required

The tag’s key

value · string · required

The tag’s value

dimension_display_name · string

Display name for the tag dimension

value_display_name · string

Display name for the tag value

dimension_id · string · required

ID of the tag dimension

definition_id · string · required

ID of the tag value definition

created_at · ISO8601 timestamp · required

When the tag was created

updated_at · ISO8601 timestamp · required

When the tag was last updated

deleted_at · ISO8601 timestamp

When the tag was deleted

archived_at · ISO8601 timestamp

When the tag was archived

transaction_tags · Array of Tags

Show Tag properties

id · string · required

Unique identifier for the tag

key · string · required

The tag’s key

value · string · required

The tag’s value

dimension_display_name · string

Display name for the tag dimension

value_display_name · string

Display name for the tag value

dimension_id · string · required

ID of the tag dimension

definition_id · string · required

ID of the tag value definition

created_at · ISO8601 timestamp · required

When the tag was created

updated_at · ISO8601 timestamp · required

When the tag was last updated

deleted_at · ISO8601 timestamp

When the tag was deleted

archived_at · ISO8601 timestamp

When the tag was archived

memo · string

Memo for any text you would like to associate with the invoice payment (for example, to display to end users).

metadata · object

Arbitrary custom metadata in JSON format with a size limit of 1KB.

reference_number · string

Any (typically user-visible) identifier you would like to associate with the invoice payment. Can be used to filter when listing invoice payment.

Response

 {
   "data": {
     "type": "Payment",
     "id": "e67c216b-28f4-4a0e-9a21-7f05c19e4c66",
     "external_id": "payment-1",
     "customer": {
       "type": "CustomerData",
       "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
       "external_id": "customer-1",
       "individual_name": "John Doe",
       "company_name": null,
       "email": "[e-mail]"
     },
     "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": {}
   }
 }

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

dedicated_refunds · array of CreateDedicatedRefundParams objects

List of Dedicated Refunds to create with this payment