Skip to main content
PUT
/
v1
/
businesses
/
{businessId}
/
invoices
/
refunds
/
{refundId}
Update refund
curl --request PUT \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/invoices/refunds/{refundId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refunded_amount": 123,
  "completed_at": "2023-11-07T05:31:56Z",
  "allocations": [
    {
      "total_amount": 123,
      "line_items": [
        {
          "amount": 123,
          "external_id": "<string>",
          "account_identifier": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "prepayment_account_identifier": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "tags": [
            {
              "key": "department",
              "value": "sales",
              "dimension_display_name": "Department",
              "value_display_name": "Sales Department"
            }
          ],
          "memo": "<string>",
          "metadata": {
            "custom_field": "value",
            "any valid json": "below 1kb",
            "nested": {
              "meaning of life": 42,
              "array": []
            }
          },
          "reference_number": "<string>"
        }
      ],
      "external_id": "<string>",
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_external_id": "<string>",
      "invoice_line_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_line_item_external_id": "<string>",
      "invoice_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_payment_external_id": "<string>",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_external_id": "<string>",
      "tags": [
        {
          "key": "department",
          "value": "sales",
          "dimension_display_name": "Department",
          "value_display_name": "Sales Department"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "payments": [
    {
      "refunded_amount": 123,
      "completed_at": "2023-11-07T05:31:56Z",
      "method": "CASH",
      "external_id": "31415926535",
      "refund_processing_fee": 123,
      "processor": "STRIPE",
      "payment_clearing_account_identifier": {
        "type": "AccountId",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "refunded_payment_fees": [
        {
          "account": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "fee_amount": 123,
          "description": "<string>"
        }
      ],
      "tags": [
        {
          "key": "department",
          "value": "sales",
          "dimension_display_name": "Department",
          "value_display_name": "Sales Department"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "external_id": "<string>",
  "tags": [
    {
      "key": "department",
      "value": "sales",
      "dimension_display_name": "Department",
      "value_display_name": "Sales Department"
    }
  ],
  "memo": "<string>",
  "metadata": {
    "custom_field": "value",
    "any valid json": "below 1kb",
    "nested": {
      "meaning of life": 42,
      "array": []
    }
  },
  "reference_number": "<string>",
  "payment_clearing_account_identifier": {
    "type": "AccountId",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_id": "31415926535",
  "refunded_amount": 123,
  "status": "PAID",
  "completed_at": "2023-11-07T05:31:56Z",
  "is_dedicated": true,
  "allocations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": 123,
      "account_identifier": {
        "type": "AccountId",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "invoice_external_id": "<string>",
      "invoice_line_item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_line_item_external_id": "<string>",
      "invoice_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_payment_external_id": "<string>",
      "customer": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "external_id": "31415926535",
        "individual_name": "<string>",
        "company_name": "<string>",
        "email": "<string>",
        "mobile_phone": "<string>",
        "office_phone": "<string>",
        "address_string": "<string>",
        "memo": "<string>",
        "status": "ACTIVE",
        "transaction_tags": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "key": "ExampleTagKey",
            "value": "ExampleTagValue",
            "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "dimension_display_name": "<string>",
            "value_display_name": "<string>",
            "archived_at": "2023-11-07T05:31:56Z"
          }
        ]
      },
      "transaction_tags": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "key": "ExampleTagKey",
          "value": "ExampleTagValue",
          "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dimension_display_name": "<string>",
          "value_display_name": "<string>",
          "archived_at": "2023-11-07T05:31:56Z"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "payments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "31415926535",
      "refunded_amount": 123,
      "fee": 123,
      "completed_at": "2023-11-07T05:31:56Z",
      "method": "CREDIT_CARD",
      "processor": "STRIPE",
      "payment_clearing_account": {
        "id": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "name": "Current Assets",
        "account_number": "4000",
        "stable_name": {
          "type": "StableName",
          "stable_name": "CURRENT_ASSETS"
        },
        "normality": "CREDIT",
        "account_type": {
          "value": "ASSET",
          "display_name": "Asset"
        },
        "account_subtype": {
          "value": "BANK_ACCOUNTS",
          "display_name": "Current Assets"
        }
      },
      "refunded_payment_fees": [
        {
          "account": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "description": "<string>",
          "fee_amount": 123
        }
      ],
      "transaction_tags": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "key": "ExampleTagKey",
          "value": "ExampleTagValue",
          "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dimension_display_name": "<string>",
          "value_display_name": "<string>",
          "archived_at": "2023-11-07T05:31:56Z"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "payouts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "payout-1234",
      "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "paid_out_amount": 123,
      "fee": 123,
      "processor": "STRIPE",
      "imported_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "match": {
        "id": "6b0a3734-f4ef-4fb0-9fc1-3f59b0c1cf99",
        "match_type": "PAYOUT",
        "bank_transaction": {
          "type": "Bank_Transaction_Data",
          "id": "a703c8d6-cfe8-453d-a275-b92eacc6fc6e",
          "business_id": "738ec216-e8e5-48f2-b7f2-cdc89c96b3d4",
          "source": "STRIPE",
          "source_transaction_id": "trxn_1sdOeLQiFAKE2LQBkcvrJw95f",
          "source_account_id": "738ec216-e154-48f2-1111-cdc89c96b3d4",
          "imported_at": "2024-03-19T22:09:53.290591Z",
          "date": "2024-03-06T06:06:40Z",
          "direction": "CREDIT",
          "amount": 87459,
          "counterparty_name": null,
          "description": "Payout (po_1OqnTHISISFAKEiTVBkCiyAERwm).",
          "account_name": "Layer Banking",
          "categorization_status": "MATCHED"
        },
        "details": {
          "type": "Payout_Match",
          "id": "d224508b-b05e-41da-89de-0fbd8a573507",
          "amount": 87459,
          "date": "2024-03-06T00:00:00Z",
          "description": "Payout from STRIPE.",
          "adjustment": null
        }
      },
      "transaction_tags": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "key": "ExampleTagKey",
          "value": "ExampleTagValue",
          "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dimension_display_name": "<string>",
          "value_display_name": "<string>",
          "archived_at": "2023-11-07T05:31:56Z"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "transaction_tags": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "key": "ExampleTagKey",
      "value": "ExampleTagValue",
      "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "dimension_display_name": "<string>",
      "value_display_name": "<string>",
      "archived_at": "2023-11-07T05:31:56Z"
    }
  ],
  "memo": "<string>",
  "metadata": {
    "custom_field": "value",
    "any valid json": "below 1kb",
    "nested": {
      "meaning of life": 42,
      "array": []
    }
  },
  "reference_number": "<string>"
}

Authorizations

ā€‹
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

ā€‹
Content-Type
string

Content-Type must be set to application/json.

Path Parameters

ā€‹
businessId
string
required

The UUID of the business to update the refund for.

ā€‹
refundId
string
required

The UUID of the refund to update.

Body

application/json

Itemized refund creation parameters. Provides full control over refund allocations and payments. The sum of allocation amounts must equal the refunded_amount.

ā€‹
refunded_amount
integer<int64>
required

The total amount of the refund in cents. This value must be positive and equal to the sum of all allocation amounts.

ā€‹
completed_at
string<date-time>
required

The time the refund was completed.

ā€‹
allocations
object[]
required

The targets of the refund. Each allocation specifies how much of the refund should be applied to a specific invoice, line item, payment, or customer.

ā€‹
payments
object[]
required

The payment methods and amounts used to process the refund.

ā€‹
external_id
string | null

An external identifier for the refund transaction.

ā€‹
tags
object[]

Tags to associate with the refund.

ā€‹
memo
string | null

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

ā€‹
metadata
object

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

Example:
{
  "custom_field": "value",
  "any valid json": "below 1kb",
  "nested": { "meaning of life": 42, "array": [] }
}
ā€‹
reference_number
string | null

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

ā€‹
payment_clearing_account_identifier
Account ID Ā· object

Optional account identifier to specify the clearing account for inferred refund payments. Only used when the payments field is not provided and the system automatically generates a payment based on the method field.

Response

Refund updated successfully.

A refund represents a transaction that returns value to from a business to a customer. A specific payment can be refunded or a general refund can be applied to an invoice.

ā€‹
id
string<uuid>

Unique identifier for the refund.

ā€‹
external_id
string

Unique ID of the refund in your system for linking purposes. Idempotency key.

Example:

"31415926535"

ā€‹
refunded_amount
integer<int64>

Amount refunded to the customer in cents.

ā€‹
status
string

Status of the refund.

Example:

"PAID"

ā€‹
completed_at
string<date-time>

Time when the refund was completed.

ā€‹
is_dedicated
boolean

Whether this refund is dedicated or not. Dedicated refunds can only have one allocation and one payment.

Example:

true

ā€‹
allocations
object[]

Allocations associated with this refund.

ā€‹
payments
object[]

Payments associated with this refund.

ā€‹
payouts
object[]

Payouts associated with this refund.

ā€‹
transaction_tags
object[]
ā€‹
memo
string | null

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

ā€‹
metadata
object

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

Example:
{
  "custom_field": "value",
  "any valid json": "below 1kb",
  "nested": { "meaning of life": 42, "array": [] }
}
ā€‹
reference_number
string | null

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