payment

InsuranceAuto InsuranceTelematicsEmbedded InsurancePolicy AdministrationClaimsUsage-Based InsuranceInsurTech

Properties

Name	Type	Description
payment_id	string	Must be a UUID. The unique identifier of the payment.
policy_id	string	Must be a UUID. The unique identified of the policy the payment is linked to.
payment_method_id	string	Must be a UUID. The unique identifier of the payment method used to make the payment.
status	object
amount	numbernull	The payment amount as an integer in cents.
description	string	Description of the payment.
external_ref	stringnull	Unique external reference of the payment.
customer_ref	stringnull	Customer reference for the payment.
created_at	string	The time at which the payment was created.
created_by	object	An object indicating the user or API key that created the policyholder.
updated_at	string	Date the payment was last updated.
billing_date	string	The customer's chosen payment date, as specified using the `billing_day` property on the policy.
payment_date	string	The target date for the payment to go off the customer’s card or bank account. Typically the same as `billing_date`, but may be earlier or later if `billing_date` falls on a bank holiday or Sunday.
action_date	string	The date that the system first attempts to collect the payment from the customer's card or bank account. Typically the same as the `payment_date`, but can be earlier for certain payment methods.
payment_method	object
payment_type	object
premium_type	object
app_data	objectnull	`null` is allowed. An object containing additional custom data for the payment.
failure_reason	stringnull	The reason the payment failed.
currency	string	Three-digit currency code for the payment. E.g. `ZAR` or `GBP`
retry_of	string	Must be a UUID. Only relevant for retry payments. Original payment id of the payment being retried.
retry_number	numbernull	`null` is allowed. Only relevant for retry payments. The number of times the payment has been retried (including the current retry payment).
net_amount	number	Integer in cents. The payment amount net of any charges.
finalized_at	string	The date the payment update was finalized.
finalized_by	object	`null` is allowed. An object indicating the user or API key that finalized the payment.
collection_type	object
policyholder	object	`null` is allowed. The policyholder linked to the payment.
policy	object	`null` is allowed. The policy the payment is linked to.
charges	array	Whenever a premium payment is created (including reversals), a breakdown of the payment amount is calculated according to the charges stored on the policy.
raw_response	stringnull	The raw response from upstream providers.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "payment",
  "type": "object",
  "required": [
    "payment_id",
    "policy_id",
    "payment_method_id",
    "status",
    "amount",
    "created_at",
    "created_by",
    "updated_at",
    "payment_date",
    "action_date",
    "billing_date",
    "policy",
    "policyholder",
    "payment_method",
    "payment_type",
    "currency",
    "retry_number",
    "app_data",
    "raw_response"
  ],
  "properties": {
    "payment_id": {
      "type": "string",
      "description": "Must be a UUID. The unique identifier of the payment."
    },
    "policy_id": {
      "type": "string",
      "description": "Must be a UUID. The unique identified of the policy the payment is linked to."
    },
    "payment_method_id": {
      "type": "string",
      "description": "Must be a UUID. The unique identifier of the payment method used to make the payment."
    },
    "status": {
      "$ref": "#/components/schemas/payment-status"
    },
    "amount": {
      "type": [
        "number",
        "null"
      ],
      "description": "The payment amount as an integer in cents."
    },
    "description": {
      "type": "string",
      "description": "Description of the payment."
    },
    "external_ref": {
      "type": [
        "string",
        "null"
      ],
      "description": "Unique external reference of the payment."
    },
    "customer_ref": {
      "type": [
        "string",
        "null"
      ],
      "description": "Customer reference for the payment."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time at which the payment was created."
    },
    "created_by": {
      "type": "object",
      "description": "An object indicating the user or API key that created the policyholder.",
      "required": [
        "type"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the actor."
        },
        "type": {
          "$ref": "#/components/schemas/actor-type"
        },
        "owner_id": {
          "type": "string",
          "description": "The related organisation's UUID."
        }
      }
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Date the payment was last updated."
    },
    "billing_date": {
      "type": "string",
      "format": "date-time",
      "description": "The customer's chosen payment date, as specified using the `billing_day` property on the policy."
    },
    "payment_date": {
      "type": "string",
      "format": "date-time",
      "description": "The target date for the payment to go off the customer\u2019s card or bank account. Typically the same as `billing_date`, but may be earlier or later if `billing_date` falls on a bank holiday or Sunday."
    },
    "action_date": {
      "type": "string",
      "format": "date-time",
      "description": "The date that the system first attempts to collect the payment from the customer's card or bank account. Typically the same as the `payment_date`, but can be earlier for certain payment methods."
    },
    "payment_method": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/payment-method"
        },
        {
          "type": "null"
        }
      ]
    },
    "payment_type": {
      "$ref": "#/components/schemas/payment-type"
    },
    "premium_type": {
      "$ref": "#/components/schemas/premium-type"
    },
    "app_data": {
      "type": [
        "object",
        "null"
      ],
      "description": "`null` is allowed. An object containing additional custom data for the payment.",
      "additionalProperties": true
    },
    "failure_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "The reason the payment failed.\n"
    },
    "currency": {
      "type": "string",
      "description": "Three-digit currency code for the payment. E.g. `ZAR` or `GBP`"
    },
    "retry_of": {
      "type": "string",
      "description": "Must be a UUID. Only relevant for retry payments. Original payment id of the payment being retried."
    },
    "retry_number": {
      "type": [
        "number",
        "null"
      ],
      "description": "`null` is allowed. Only relevant for retry payments. The number of times the payment has been retried (including the current retry payment).\n"
    },
    "net_amount": {
      "type": "number",
      "description": "Integer in cents. The payment amount net of any charges."
    },
    "finalized_at": {
      "type": "string",
      "format": "date-time",
      "description": "The date the payment update was finalized."
    },
    "finalized_by": {
      "type": "object",
      "description": "`null` is allowed. An object indicating the user or API key that finalized the payment.",
      "required": [
        "type"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the actor e.g. user"
        },
        "type": {
          "$ref": "#/components/schemas/actor-type"
        },
        "owner_id": {
          "type": "string",
          "description": "The related organisation's UUID"
        }
      }
    },
    "collection_type": {
      "$ref": "#/components/schemas/collection-type"
    },
    "policyholder": {
      "description": "`null` is allowed. The policyholder linked to the payment.",
      "anyOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/components/schemas/policyholder"
        }
      ]
    },
    "policy": {
      "description": "`null` is allowed. The policy the payment is linked to.",
      "anyOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/components/schemas/policy"
        }
      ]
    },
    "charges": {
      "type": "array",
      "description": "Whenever a premium payment is created (including reversals), a breakdown of the payment amount is calculated according to the charges stored on the policy.",
      "items": {
        "type": "object",
        "required": [
          "type",
          "name",
          "description",
          "amount",
          "calculated"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/payment-charge-type"
          },
          "name": {
            "type": "string",
            "description": "The name of the charge."
          },
          "description": {
            "type": "string",
            "description": "The description of the charge."
          },
          "amount": {
            "type": "integer",
            "description": "The charged amount. Required when type is `fixed` or `variable`. Either a proportion of the total premium (if `type` is `variable`), or a currency amount in cents (if `type` is `fixed`)."
          },
          "calculated": {
            "type": "integer",
            "description": "The final calculated charge amount."
          }
        }
      }
    },
    "raw_response": {
      "type": [
        "string",
        "null"
      ],
      "description": "The raw response from upstream providers."
    }
  },
  "example": [
    {
      "payment_id": "c9625104-c8da-45e2-972f-baf3037bce6b",
      "policy_id": "07f9b73e-d16d-4a5a-8463-44ee62de4da3",
      "payment_method_id": "ff80fa5b-6daf-4c3c-9ca1-bb442a796aa6",
      "status": "failed",
      "amount": 100,
      "description": "monthly_premium",
      "external_ref": "ExternalSystem00001",
      "customer_ref": null,
      "created_at": "2022-10-28T14:17:21.441Z",
      "created_by": {
        "type": "api_key",
        "id": "312d8c45-eb3a-4f18-a952-c358fb94abdc",
        "owner_id": "cb8a0648-9186-454d-bf1f-6d82b3b82894"
      },
      "updated_at": "2022-10-28T14:17:38.798Z",
      "payment_date": "2022-10-26T00:00:00.000Z",
      "action_date": "2022-10-26T00:00:00.000Z",
      "billing_date": "2022-10-26T00:00:00.000Z",
      "policy": null,
      "policyholder": null,
      "payment_method": null,
      "payment_type": "premium",
      "premium_type": "recurring",
      "failure_reason": "Account Closed",
      "currency": "ZAR",
      "retry_number": 0,
      "finalized_at": "2022-10-28T14:17:38.798Z",
      "finalized_by": {
        "type": "api_key",
        "id": "312d8c45-eb3a-4f18-a952-c358fb94abdc",
        "owner_id": "cb8a0648-9186-454d-bf1f-6d82b3b82894"
      },
      "collection_type": "debit_order_two_day",
      "app_data": {},
      "charges": [],
      "raw_response": null
    }
  ]
}