Root Insurance Payments API

The Payments API from Root Insurance — 6 operation(s) for payments.

Operations 6

PATCH /payment-batches/{payment_batch_id} Update a payment batch #
POST /payments/async-create Create payments async #
POST /payments/async-update Update payments async #
PUT /payments/{payment_id} Update payment #
POST /scheduled-payments/{scheduled_payment_id}/reschedule Reschedule a scheduled payment #
POST /scheduled-payments/{scheduled_payment_id}/unschedule Unschedule a scheduled payment #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/root-payments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

root-payments-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  version: 1.0.1
  title: Root Applications Payments API
  description: Root is an end-to-end digital insurance platform that enables you to launch new products and digital engagement channels fast.
  termsOfService: https://rootplatform.com/about
  contact:
    name: Root support team
    url: https://rootplatform.com/contact
    email: support@root.co.za
servers:
- url: https://sandbox.uk.rootplatform.com/v1/insurance
  description: United Kingdom multi-tenant - sandbox
- url: https://api.uk.rootplatform.com/v1/insurance
  description: United Kingdom multi-tenant - production
- url: https://sandbox.rootplatform.com/v1/insurance
  description: South Africa multi-tenant - sandbox
- url: https://api.rootplatform.com/v1/insurance
  description: South Africa multi-tenant - production
security:
- basicAuth: []
tags:
- name: Payments
paths:
  /payment-batches/{payment_batch_id}:
    patch:
      operationId: update-payment-batch
      summary: Update a payment batch
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - name: payment_batch_id
        in: path
        description: Must be a UUID. The unique identifier of the payment batch.
        required: true
        schema:
          type: string
          example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              - failure_reason
              properties:
                status:
                  type: string
                  description: The payment batch status to update to. Must be one of [`accepted`, `failed`].
                failure_reason:
                  type: string
                  description: A description of the reason the payment batch failed.
              example:
                status: failed
                failure_reason: Failed validation
            example:
              status: failed
              failure_reason: Failed validation
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-batch'
              example:
                payment_batch_id: 00000000-0000-0000-0000-000000000001
                organization_id: 00000000-0000-0000-0000-000000000001
                status: failed
                action_date: '2021-09-29T09:36:43.560Z'
                process_date: '2021-09-29T09:36:43.560Z'
                payment_type: debit_order_same_day
                payment_method_type: debit_order
                billing_config_id: 00000000-0000-0000-0000-000000000003
                submitted_at: '2021-10-07T07:38:00.117Z'
                submitted_by:
                  type: api_key
                  id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
                  owner_id: 00000000-0000-0000-0000-000000000001
                created_at: '2021-09-29T09:36:43.560Z'
                failure_reason: Failed validation
                num_payments: 10
                num_reviewed: 0
                total_value: 1000000
                external_reference: ABCDE12345
                updated_at: '2021-10-07T07:38:00.117Z'
                updated_by:
                  type: api_key
                  id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
                  owner_id: 00000000-0000-0000-0000-000000000001
  /payments/async-create:
    post:
      operationId: async-payments-create
      deprecated: true
      summary: Create payments async
      description: 'This endpoint is deprecated in favour of [create payment](ref:createpolicypayment). This endpoint validates the input and queues payments to be processed asynchronously. A response of `200 OK` is sent if the payments are valid and have been successfully queued. This endpoint allows for up to 5000 payments to be created at a time. To use this endpoint you''ll need the `Payments Create` permission.

        '
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-creates-async-array'
      responses:
        '200':
          description: Success
  /payments/async-update:
    post:
      operationId: update-payments-async
      summary: Update payments async
      description: This endpoint validates the input and queues [payment updates](ref:payment-update) to be processed asynchronously, which will result in a `200 OK` successful response. **Note:** Despite a successful response, queued updates can nevertheless fail. To receive the update failure / success status, subscribe to the `payment_updates_succeeded` and `payment_updates_failed` [webhooks](ref:create-webhook).
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-updates'
      responses:
        '200':
          description: Success
  /payments/{payment_id}:
    put:
      operationId: update-payment
      summary: Update payment
      description: This endpoint validates the input and updates a payment, which will result in a `200 OK` successful response, with the updated payment in the response.
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - name: payment_id
        in: path
        description: The unique identifier of the [payment](ref:payment).
        required: true
        schema:
          type: string
          example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-update'
            example:
              $ref: '#/components/schemas/payment-update/example'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-response'
              example:
                payment_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
                policy_id: 2b012979-e2a2-45d3-b5fe-729f825d96ce
                payment_method_id: f4863a40-a6b1-4a4b-b734-62ae0370cd70
                status: successful
                amount: 6000
                description: Monthly premium for August
                customer_ref: ABCDEFGHIJ
                created_at: '2022-10-12T15:47:34.281Z'
                created_by:
                  id: 00000000-0000-0000-0000-000000000001
                  type: user
                updated_at: '2022-10-12T15:47:34.281Z'
                payment_date: '2022-10-12T00:00:00.000Z'
                action_date: '2022-10-12T00:00:00.000Z'
                policy: null
                policyholder: null
                payment_method: null
                payment_type: premium
                currency: ZAR
                finalized_at: '2022-09-19T12:47:57.546Z'
                finalized_by:
                  type: api_key
                  id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
                  owner_id: 00000000-0000-0000-0000-000000000001
                app_data: null
                charges: []
                raw_response: null
  /scheduled-payments/{scheduled_payment_id}/reschedule:
    post:
      operationId: reschedule-scheduled-payment
      summary: Reschedule a scheduled payment
      description: Moves a pending scheduled payment to a new date. The caller must pass the schedule's current `version` for optimistic-locking; a stale version returns `409 Conflict`. Only pending schedules can be rescheduled. Returns `200 OK` with the scheduled payment id on success.
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - name: scheduled_payment_id
        in: path
        description: The unique identifier of the scheduled payment.
        required: true
        schema:
          type: string
          example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - scheduled_for
              - version
              properties:
                scheduled_for:
                  type: string
                  format: date-time
                  description: The new date to attempt collection on. Must not be in the past.
                  example: '2026-07-01T00:00:00.000Z'
                reason:
                  type: string
                  description: Optional free-text note on why the schedule was moved.
                  example: Customer requested a later debit date.
                version:
                  type: integer
                  description: The schedule's current version, for optimistic-locking.
                  example: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  scheduled_payment_id:
                    type: string
              example:
                scheduled_payment_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
        '409':
          description: The schedule is not pending, or the supplied version is stale.
  /scheduled-payments/{scheduled_payment_id}/unschedule:
    post:
      operationId: unschedule-scheduled-payment
      summary: Unschedule a scheduled payment
      description: Cancels a pending scheduled payment so it will not be collected. The caller must pass the schedule's current `version` for optimistic-locking; a stale version returns `409 Conflict`. Only pending schedules can be unscheduled. Returns `200 OK` with the scheduled payment id on success.
      tags:
      - Payments
      x-additional-tags:
      - Endpoints
      parameters:
      - name: scheduled_payment_id
        in: path
        description: The unique identifier of the scheduled payment.
        required: true
        schema:
          type: string
          example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
      - $ref: '#/components/parameters/idempotency'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - reason
              - version
              properties:
                reason:
                  type: string
                  description: Why the schedule was cancelled.
                  enum:
                  - manual_admin
                  - payment_method_revoked
                  - policy_cancelled
                  example: payment_method_revoked
                version:
                  type: integer
                  description: The schedule's current version, for optimistic-locking.
                  example: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  scheduled_payment_id:
                    type: string
              example:
                scheduled_payment_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
        '409':
          description: The schedule is not pending, or the supplied version is stale.
components:
  schemas:
    premium-type:
      type: string
      description: The type of the payment being created.Required when `payment_type` is premium or reversal, optional when `payment_type` is premium_refund, forbidden otherwise.
      enum:
      - recurring
      - arrears
      - ad_hoc
      - pro_rata
      - cover_period
      - collection_request
      - manual_eft
      - premium_refund
    payment-updates:
      type: array
      items:
        $ref: '#/components/schemas/payment-update'
      example:
      - payment_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
        status: successful
      - payment_id: bd0c2ab2-4bf9-4786-9d90-0588fdff2600
        status: processing
      - payment_id: 0463e674-ff1b-475d-901b-c37b01ab1ef6
        status: failed
        failure_reason: Not provided for
        failure_action: block_retry
      - payment_id: 96e06845-6d37-4dca-8859-9d8ed27dcf58
        status: failed
        failure_reason: Account closed
        failure_action: block_payment_method
    policyholder:
      type: object
      required:
      - policyholder_id
      - type
      - id
      - first_name
      - last_name
      - policy_ids
      - created_at
      - app_data
      - created_by
      properties:
        policyholder_id:
          type: string
          description: Must be a UUID. The unique identifier of the policyholder.
        type:
          type: string
          description: The policyholder type.
          enum:
          - individual
          - company
        id:
          type: object
          description: (Individual policyholders only) Object containing policyholder's identification information.
          properties:
            type:
              type: string
              description: The id type of the policyholder.
              enum:
              - id
              - passport
              - email
              - cellphone
              - custom
            number:
              type: string
              description: The ID or passport number.
            country:
              type: string
              description: The [ISO Alpha-2](http://www.nationsonline.org/oneworld/country_code_list.htm) country code of the country of the id/passport number.
            expiration_date:
              type: string
              format: date-time
              description: (Individual policyholders only) The expiration date of the policyholder's passport.
          required:
          - type
          - number
          - country
        title:
          type: string
          description: The policyholders's title.
          enum:
          - mr
          - mrs
          - miss
          - mx
          - sir
          - dr
          - adv
          - ms
          - prof
        date_of_birth:
          type: string
          description: (Individual policyholders only) The policyholder's date of birth in the format YYYYMMDD.
        gender:
          type: string
          description: Null is allowed. (Individual policyholders only) The policyholder's gender.
          enum:
          - male
          - female
        initials:
          type:
          - string
          - 'null'
          description: '`null` is allowed. The policyholder or primary contact''s initials.'
        first_name:
          type: string
          description: The policyholder or primary contact's legal first name.
        middle_name:
          type:
          - string
          - 'null'
          description: '`null` is allowed. The policyholder or primary contact''s legal middle name.'
        last_name:
          type: string
          description: The policyholder or primary contact's legal last name.
        company_name:
          type: string
          description: (Company policyholders only) The name of the company that the policyholder represents.
        registration_number:
          type: string
          description: (Company policyholders only) The company's registration number.
        date_of_establishment:
          type: string
          description: (Company policyholders only) The company's date of establishment in the format YYYYMMDD.
        company_website_url:
          type: string
          description: (Company policyholders only) The company's website URL.
        contact_position:
          type: string
          description: (Company policyholders only) The position or role of the primary contact at the company.
        subsidiary_companies:
          type: array
          items:
            type: string
          description: (Company policyholders only) An array of subsidiary company names.
        email:
          type:
          - string
          - 'null'
          description: '`null` is allowed. The policyholder or primary contact''s contact email address.'
        cellphone:
          $ref: '#/components/schemas/cellphone-string'
        phone_other:
          $ref: '#/components/schemas/cellphone-string'
        policy_ids:
          type: array
          items:
            type: string
          description: An array of ids of the policies linked to this policyholder.
        policies:
          type: array
          items:
            $ref: '#/components/schemas/policy'
          description: An array of full [policy objects](#policy) owned by the policyholder. This is currently only included when [fetching all policyholders](#list-all-policyholders) or [fetching an individual policyholder](#retrieve-a-policyholder) with `?include=policies`.
        created_at:
          type: string
          format: date-time
          description: The time at which the policyholder was created.
        app_data:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object containing additional custom data for the policy holder.'
          additionalProperties: true
        created_by:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object indicating the user or API key that created the policyholder. See [Authentication](#client-apps).'
        updated_at:
          type: string
          format: date-time
          description: The time at which the policyholder was last updated.
        address:
          type:
          - object
          - 'null'
          description: '`null` is allowed. The policyholder''s physical address. See below for more details.'
          properties:
            line_1:
              type: string
              description: First line of the policyholder's address.
            line_2:
              type:
              - string
              - 'null'
              description: '`null` is allowed. Optional second line of the policyholder''s address.'
            suburb:
              type: string
              description: The policyholder's suburb.
            city:
              type: string
              description: The policyholder's city.
            country:
              type: string
              description: The policyholder's country code, in the [ISO Alpha-2](http://www.nationsonline.org/oneworld/country_code_list.htm) format.
            area_code:
              type: string
              description: The policyholder's area code must be 4 characters long for South African addresses.
          required:
          - line_1
          - city
          - country
          - area_code
      example:
        policyholder_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
        type: individual
        initials: E
        first_name: Erlich
        middle_name: Aviato
        last_name: Bachman
        id:
          type: id
          number: '6801015800084'
          country: ZA
        date_of_birth: '19680101'
        gender: male
        email: erlich@aviato.com
        cellphone: '+27821234567'
        phone_other: '+27124101337'
        created_at: '2017-10-12T15:47:34.281Z'
        app_data:
          company: Aviato
        policy_ids: []
        created_by:
          id: 00000000-0000-0000-0000-000000000001
          type: user
        address:
          line_1: 5230 Penfield Avenue
          suburb: Woodland Hills
          city: Los Angeles
          country: US
          area_code: CA 91364
    actor-type:
      type: string
      description: The actor who created the record.
      enum:
      - api_key
      - system
      - user
    payment-response:
      type: object
      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 identifier of the policy linked to the payment.
        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
          description: The payment amount as an integer in cents.
        description:
          type: string
          description: Description of the payment.
        external_ref:
          type: string
          description: Unique external reference of 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.
          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.
        payment_date:
          type: string
          format: date-time
          description: 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:
          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.
        billing_date:
          type: string
          format: date-time
          description: Date the payment should be processed.
        payment_method:
          description: '`null` is allowed. The payment method used for the payment.'
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/payment-method'
        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
          description: 'The reason the payment failed.

            '
        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.
        finalized_at:
          type: string
          format: date-time
          description: The date the payment update was finalized.
        collection_type:
          $ref: '#/components/schemas/collection-type'
        policyholder:
          description: '`null` is allowed. The policyholder the payment is linked to.'
          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
            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:
          - object
          - 'null'
          description: '`null` is allowed. An object containing additional custom data for the payment.'
    beneficiary-relationship:
      type: string
      description: The beneficiary's relationship to the policyholder.
      enum:
      - main_member
      - spouse
      - parent
      - son
      - daughter
      - aunt_or_uncle
      - grandparent
      - cousin_or_relative
      - brother
      - sister
      - employer
      - policyholder
      - credit_provider
      - cessionary
      - estate
      - trust
      - guardian_fund
      - funeral_parlour
      - son_in_law
      - daughter_in_law
      - mother_in_law
      - father_in_law
      - grandchild
      - niece_or_nephew
      - other
    policy-status:
      type: string
      description: The policy status. See the [managing policies](https://docs.rootplatform.com/docs/policy-administration#policy-lifecycle) guide for more details on the policy lifecycle.
      enum:
      - pending_initial_payment
      - active
      - cancelled
      - expired
      - lapsed
      - not_taken_up
    payment-batch:
      type: object
      required:
      - organization_id
      - payment_batch_id
      - status
      - action_date
      - process_date
      - payment_type
      - payment_method_type
      - billing_config_id
      - submitted_at
      - submitted_by
      - created_at
      - failure_reason
      - num_payments
      - num_reviewed
      - total_value
      - external_reference
      - updated_at
      - updated_by
      properties:
        organization_id:
          type: string
          description: Must be a UUID. The unique identifier of the organization.
        payment_batch_id:
          type: string
          description: Must be a UUID. The unique identifier of the payment batch.
        status:
          type: string
          description: The payment batch status, one of [`pending`, `submitting`, `submitted`, 'accepted', `failed`, `archived`].
        action_date:
          type: string
          format: date-time
          description: The time at which the payments in the batch will strike the accounts.
        process_date:
          type: string
          format: date-time
          description: The time at which the batch should be processed & submitted by.
        payment_type:
          type: string
          description: The payment collection type, one of [`debit_order_same_day`, `debit_order_two_day`, `debit_order_naedo` (deprecated), `debit_order_debicheck`, `card`, `external`, `other`].
        payment_method_type:
          type: string
          description: The payment method type, one of [`debit_order`, `card`, `eft`, `external`].
        billing_config_id:
          type: string
          description: Must be a UUID. The unique identifier of the billing config to be used when processing this batch.
        submitted_at:
          type: string
          format: date-time
          description: The time at which the batch was submitted.
        submitted_by:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object indicating the user or API key that submitted the batch. See [Authentication](#client-apps).'
        created_at:
          type: string
          format: date-time
          description: The time at which the batch was created.
        failure_reason:
          type: string
          description: A description of the reason the payment batch failed.
        num_payments:
          type: integer
          description: The number of payments included in this batch.
        num_reviewed:
          type: integer
          description: The number of payments in this batch that have been reviewed.
        total_value:
          type: integer
          description: The total amount of premium, in cents, of the all the payments in this batch.
        external_reference:
          type:
          - string
          - 'null'
          description: External reference used for identifying the batch.
        updated_at:
          type: string
          format: date-time
          description: The time at which the batch was updated.
        updated_by:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object indicating the user or API key that updated the batch. See [Authentication](#client-apps).'
      example:
        payment_batch_id: 00000000-0000-0000-0000-000000000001
        organization_id: 00000000-0000-0000-0000-000000000001
        status: submitted
        action_date: '2021-09-29T09:36:43.560Z'
        process_date: '2021-09-29T09:36:43.560Z'
        payment_type: debit_order_same_day
        payment_method_type: debit_order
        billing_config_id: 00000000-0000-0000-0000-000000000003
        submitted_at: '2021-10-07T07:38:00.117Z'
        submitted_by:
          type: api_key
          id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
          owner_id: 00000000-0000-0000-0000-000000000001
        created_at: '2021-09-29T09:36:43.560Z'
        failure_reason: null
        num_payments: 10
        num_reviewed: 0
        total_value: 1000000
        external_reference: ABCDE12345
        updated_at: '2021-10-07T07:38:00.117Z'
        updated_by:
          type: api_key
          id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
          owner_id: 00000000-0000-0000-0000-000000000001
    failure-action:
      type: string
      enum:
      - block_payment_method
      - block_retry
      - allow_retry
      description: 'The additional action to perform when processing a failed payment. `block_payment_method`: Set the payment method''s verification status to `blocked`, and do not generate a retry. `block_retry`: Do not generate a retry payment (even if enabled in the [product module settings](doc:billing-settings)). `allow_retry`: Generate a retry payment (if enabled in the [product module settings](doc:billing-settings)). **Note:** The payment method will be blocked after 4 consecutive failed payments regardless. See the [billing settings](https://docs.rootplatform.com/docs/billing-settings#consecutive-failed-payments-allowed) guide for more details on the number of consecutive payments allowed. This field will be required if `status` is `failed`, forbidden otherwise.

        '
    policy:
      type: object
      description: Policies are issued from applications, and represent binding insurance agreements. Parameters stored on the policy can be referenced in custom notifications, policy documents, data exports and external integrations. <br/><br/> See the [issuing policies](https://docs.rootplatform.com/docs/policy-issuing) guide and the [policy issue hook](https://docs.rootplatform.com/docs/policy-issue-hook) guide for more details.
      required:
      - policy_id
      - policy_number
      - status
      - policyholder_id
      - package_name
      - monthly_premium
      - billing_amount
      - balance
      - currency
      - billing_day
      - billing_frequency
      - next_billing_date
      - covered_people
      - base_premium
      - claim_ids
      - complaint_ids
      - start_date
      - end_date
      - policy_schedule_uri
      - terms_uri
      - schedule_versions
      - created_at
      - module
      - app_data
      - created_by
      - scheme_type
      - charges
      - supplementary_terms_files
      properties:
        policy_id:
          type: string
          description: Must be a UUID. Object ID of the policy.
        policy_number:
          type: string
          description: A shorter, human-readable policy identifier. This typically used in policy documents and customer notifications for ease of reference.
        sta

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/root/refs/heads/main/openapi/root-payments-api-openapi.yml