Skip to main content
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.
​
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
​
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.
​
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.
​
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.
​
transaction_tags
Array of Tags
​
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.
 {
   "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": {}
   }
 }

​
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