{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/karbonhq/json-schema/karbonhq-billing-payment-schema.json",
  "title": "BillingPayment",
  "description": "A Karbon Payment record",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/karbonhq-billing-api-openapi.yml#/components/schemas/BillingPayment",
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "description": "A Karbon payment",
      "required": [
        "PaymentKey",
        "PaymentReference",
        "PaymentType",
        "PaymentDate",
        "GrossAmount",
        "PaymentMethod"
      ],
      "properties": {
        "PaymentKey": {
          "type": "string",
          "description": "The unique key assigned to an payment by Karbon"
        },
        "PaymentReference": {
          "type": "string",
          "description": "The Karbon reference number of the payment"
        },
        "PaymentType": {
          "type": "string",
          "description": "The type of payment",
          "enum": [
            "ManualPayment",
            "ManualPaymentReversed",
            "Payment"
          ]
        },
        "PaymentDate": {
          "type": "string",
          "format": "date",
          "description": "The datestamp the payment was made, for Manual Payments this will be a datestamp"
        },
        "GrossAmount": {
          "type": "number",
          "format": "double",
          "description": "The valeu of the payment, excluding fees and taxes"
        },
        "PaymentMethod": {
          "type": "string",
          "description": "The method by which the payment was made"
        },
        "ClientKey": {
          "type": "string",
          "description": "The unique key of the client that payment was by - could be a Person or Organization"
        }
      }
    },
    {
      "$ref": "#/$defs/BillingKarbonPayment"
    },
    {
      "$ref": "#/$defs/BillingClient"
    }
  ],
  "$defs": {
    "BillingClient": {
      "required": [
        "Client"
      ],
      "description": "The details of the invoice recipient at the point in time the invoice was drafted or payment creator at the point the payment was received",
      "properties": {
        "Client": {
          "type": [
            "object",
            "null"
          ],
          "description": "The Karbon Client Billing Contact",
          "properties": {
            "ClientKey": {
              "type": "string",
              "description": "The unique key of the billed Client"
            },
            "ClientType": {
              "type": "string",
              "description": "The client type, e.g. Contact or Organization"
            },
            "Name": {
              "type": "string",
              "description": "The name of the client at the point the invoice was drafted"
            },
            "AddressLine": {
              "type": "string",
              "description": "The billing address of the cient at the point the invoice was drafted"
            },
            "City": {
              "type": "string",
              "description": "The billing address city of the cient at the point the invoice was drafted"
            },
            "StateProvinceCounty": {
              "type": "string",
              "description": "The billing address state/province/country of the cient at the point the invoice was drafted"
            },
            "ZipCode": {
              "type": "string",
              "description": "The billing address zip/postal code of the cient at the point the invoice was drafted"
            },
            "Country": {
              "type": "string",
              "description": "The billing address country of the cient at the point the invoice was drafted"
            },
            "EmailAddress": {
              "type": "string",
              "description": "The billing email address of the cient at the point the invoice was drafted"
            }
          }
        }
      }
    },
    "BillingKarbonPayment": {
      "type": "object",
      "description": "The Karbon Payment object",
      "properties": {
        "KarbonPayment": {
          "description": "Data specific to Karbon Payments",
          "type": "object",
          "properties": {
            "CardType": {
              "type": "string",
              "description": "The type of the paying card"
            },
            "CardCountry": {
              "type": [
                "string",
                "null"
              ],
              "description": "The country the paying card was issued in"
            },
            "CardFunding": {
              "type": "string",
              "description": ""
            },
            "PayoutStatus": {
              "type": "string",
              "description": "A status indicating whether the payment has been payed out"
            },
            "SurchargeAmount": {
              "type": "number",
              "format": "double",
              "description": "The amount of anr surcharge(s)"
            },
            "SurchargeTaxAmount": {
              "type": "number",
              "format": "double",
              "description": "The tax on any surcharge(s)"
            },
            "KarbonFeeAmount": {
              "type": "number",
              "format": "double",
              "description": "The amount of the Karbon fee"
            },
            "KarbonFeeTaxAmount": {
              "type": "number",
              "format": "double",
              "description": "The tax on the Karbon fee"
            },
            "NetAmount": {
              "type": "number",
              "format": "double",
              "description": "The gross amount less surcharges, fees and taxes"
            }
          }
        }
      }
    }
  }
}