Root Insurance Payment Methods API

openapi: 3.2.0
info:
  version: 1.0.1
  title: Root Applications Payment Methods 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: Payment Methods
paths:
  /payment-methods:
    get:
      operationId: list-payment-methods
      summary: List payment methods
      description: Returns a paginated list of payment methods for the organization. Use the `include` parameter to include related objects in the response.
      tags:
      - Payment Methods
      x-additional-tags:
      - Endpoints
      parameters:
      - name: page
        in: query
        description: The page number to retrieve.
        required: false
        schema:
          type: integer
          default: 1
          example: 1
      - name: page_size
        in: query
        description: The number of items to retrieve per page.
        required: false
        schema:
          type: integer
          default: 20
          example: 20
      - name: include
        in: query
        description: A comma-separated list of related objects to include in the response. Valid values are `policyholder`, `policies`, `collection_module`.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - policyholder
            - policies
            - collection_module
        style: form
        explode: false
        example: policyholder,policies
      - name: type
        in: query
        description: Filter by payment method type. Valid values include `debit_order`, `card`, `eft`, `collection_module`, or a custom external payment method key.
        required: false
        schema:
          type: string
          example: debit_order
      - name: banv_status
        in: query
        description: Filter by BANV status. Accepts multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - processing
            - verified
            - failed_verification
            - blocked
        style: form
        explode: false
        example: pending,verified
      - name: policyholder_ids
        in: query
        description: Filter by policyholder IDs. Accepts multiple UUIDs.
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: f91f4ea4-9c6d-459e-998b-a5711cbd8895
      - name: payment_method_ids
        in: query
        description: Filter by payment method IDs. Accepts multiple UUIDs.
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
        example: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
      - name: dismissed
        in: query
        description: Filter by dismissed status. Set to `true` to include only dismissed payment methods, `false` to exclude dismissed payment methods.
        required: false
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Success
          headers:
            X-Total-Count:
              description: The total number of payment methods matching the query.
              schema:
                type: integer
                example: 100
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/payment-method'
              example:
              - payment_method_id: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
                type: debit_order
                organization_id: 952bfef5-7517-47ff-bf41-08c5a66c52db
                policyholder_id: f91f4ea4-9c6d-459e-998b-a5711cbd8895
                created_at: '2021-01-29T13:12:00.968Z'
                updated_at: '2021-01-29T13:12:00.968Z'
                bank_details:
                  account_holder: Erlich Bachman
                  bank: absa
                  branch_code: '12345'
                  account_number: '123456789'
                  account_type: cheque
                  banv_status: verified
  /payment-methods/external-types:
    get:
      operationId: list-external-payment-method-types
      summary: List external payment method types
      description: Returns a list of external payment method types configured for the organization. External payment method types allow you to define custom payment methods with their own collection logic and outbound channels.
      tags:
      - Payment Methods
      x-additional-tags:
      - External
      parameters:
      - name: keys
        in: query
        description: Filter by external payment method type keys. Accepts a comma-separated list of keys.
        required: false
        schema:
          type: string
          example: my_payment_provider
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - payment_method_id
                  - organization_id
                  - environment
                  - key
                  - created_at
                  properties:
                    payment_method_id:
                      type: string
                      description: Must be a UUID. The unique identifier of the external payment method type.
                    organization_id:
                      type: string
                      description: Must be a UUID. The unique identifier of the organization.
                    environment:
                      type: string
                      description: The environment of the external payment method type.
                      enum:
                      - sandbox
                      - production
                    key:
                      type: string
                      description: The unique key identifying this external payment method type.
                    outbound_channels:
                      type: array
                      description: An array of outbound channels configured for this external payment method type. These define how payment requests are communicated to external systems.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: The type of outbound channel.
                            enum:
                            - http
                          url:
                            type: string
                            description: The URL to send payment requests to.
                    created_at:
                      type: string
                      format: date-time
                      description: The date and time at which the external payment method type was created.
                    config:
                      type: object
                      description: Configuration options for the external payment method type.
                      properties:
                        fixed_billing_day:
                          type: integer
                          description: If set, all payments will be scheduled on this day of the month.
                          minimum: 1
                          maximum: 31
                        assume_success:
                          type: boolean
                          description: If true, payments are assumed successful until explicitly marked otherwise.
                        payments_per_batch:
                          type: integer
                          description: The number of payments to include in each batch.
                        external_reference_template:
                          type: string
                          description: A template string for generating external references.
                        allow_payment_imports:
                          type: boolean
                          description: If true, payments can be imported from external systems.
                        should_debit_ledger:
                          type: boolean
                          description: If true, successful payments will debit the ledger.
                        external_reference_required:
                          type: boolean
                          description: If true, an external reference is required when creating payment methods of this type.
              example:
              - payment_method_id: 6e91fe74-aa56-4b4e-8f68-636d23d5706f
                organization_id: 952bfef5-7517-47ff-bf41-08c5a66c52db
                environment: sandbox
                key: my_payment_provider
                outbound_channels:
                - type: http
                  url: https://api.example.com/payments
                created_at: '2021-01-29T13:12:00.968Z'
                config:
                  assume_success: true
                  allow_payment_imports: true
                  should_debit_ledger: true
  /payment-methods/{payment_method_id}/verification-status:
    patch:
      operationId: update-payment-method-verification-status
      summary: Update Payment Method Verification Status
      description: 'This endpoint validates the input and updates the status of a payment method, which will result in a `200 OK` successful response, with the updated payment method in the response.

        '
      tags:
      - Payment Methods
      x-additional-tags:
      - Endpoints
      parameters:
      - name: payment_method_id
        in: path
        description: The unique identifier of the payment method.
        required: true
        schema:
          type: string
          example: 00000000-0000-0000-0000-00000000000b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - banv_status
              properties:
                banv_status:
                  type: string
                  enum:
                  - pending
                  - processing
                  - verified
                  - failed_verification
                  - blocked
                  description: The BANV status of the payment method.
                  example: blocked
                banv_response:
                  type: object
                  description: The response received when bank account verification was attempted. Required when `banv_status` is `failed_verification`.
                  example:
                    reason: Invalid account number
                blocked_reason:
                  type: string
                  description: The reason the payment method is blocked. Required when `banv_status` is `blocked`.
                  example: Fraud detected
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method'
  /payment-methods/{payment_method_id}/dismiss:
    post:
      operationId: dismiss-payment-method
      summary: Dismiss a payment method
      description: Dismisses a payment method, marking it as no longer active. Dismissed payment methods are excluded from standard queries unless explicitly requested.
      tags:
      - Payment Methods
      x-additional-tags:
      - Endpoints
      parameters:
      - name: payment_method_id
        in: path
        description: Must be a UUID. The unique identifier of the payment method.
        required: true
        schema:
          type: string
          example: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method'
              example:
                payment_method_id: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
                type: debit_order
                organization_id: 952bfef5-7517-47ff-bf41-08c5a66c52db
                policyholder_id: f91f4ea4-9c6d-459e-998b-a5711cbd8895
                created_at: '2021-01-29T13:12:00.968Z'
                updated_at: '2021-02-15T10:30:00.000Z'
                bank_details:
                  account_holder: Erlich Bachman
                  bank: absa
                  branch_code: '12345'
                  account_number: '123456789'
                  account_type: cheque
                  banv_status: verified
  /payment-methods/{payment_method_id}/manual-verify:
    post:
      operationId: manual-verify-payment-method
      summary: Manually verify a payment method
      description: Manually verifies a payment method, setting its BANV status to `verified`. This is useful when verification has been performed through an external process.
      tags:
      - Payment Methods
      x-additional-tags:
      - Endpoints
      parameters:
      - name: payment_method_id
        in: path
        description: Must be a UUID. The unique identifier of the payment method.
        required: true
        schema:
          type: string
          example: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment-method'
              example:
                payment_method_id: e0b7b222-772f-47ac-b08d-c7ba38aa1b25
                type: debit_order
                organization_id: 952bfef5-7517-47ff-bf41-08c5a66c52db
                policyholder_id: f91f4ea4-9c6d-459e-998b-a5711cbd8895
                created_at: '2021-01-29T13:12:00.968Z'
                updated_at: '2021-02-15T10:30:00.000Z'
                bank_details:
                  account_holder: Erlich Bachman
                  bank: absa
                  branch_code: '12345'
                  account_number: '123456789'
                  account_type: cheque
                  banv_status: verified
  /payment-methods/debicheck-mandates/{mandate_id}:
    get:
      operationId: get-debicheck-mandate
      summary: Get DebiCheck Mandate
      description: Retrieves a DebiCheck mandate by ID.
      tags:
      - Payment Methods
      x-additional-tags:
      - Billing & payments
      parameters:
      - name: mandate_id
        in: path
        description: The unique identifier of the DebiCheck mandate.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-00000000000a
      responses:
        '200':
          description: Successfully retrieved DebiCheck Mandate
          content:
            application/json:
              schema:
                $ref: '#/paths/~1payment-methods~1debicheck-mandates/post/responses/201/content/application~1json/schema'
    patch:
      operationId: update-debicheck-mandate
      summary: Update DebiCheck Mandate
      description: Updates a DebiCheck mandate by ID.
      tags:
      - Payment Methods
      x-additional-tags:
      - Billing & payments
      parameters:
      - name: mandate_id
        in: path
        description: The unique identifier of the DebiCheck mandate.
        required: true
        schema:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-00000000000a
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - debicheckMandateId
              - status
              properties:
                debicheckMandateId:
                  type: string
                  format: uuid
                  description: The unique identifier of the DebiCheck mandate
                  example: 00000000-0000-0000-0000-00000000000a
                status:
                  type: string
                  description: The status of the DebiCheck mandate
                  enum:
                  - pending
                  - submitted
                  - processing
                  - active
                  - rejected
                  - suspended
                  - cancelled
                  - no_response
                  example: active
                mandateRequestIdentifier:
                  type: string
                  description: The mandate request identifier
                  example: MANDATE_REQ_12345
                startDate:
                  type: string
                  format: date-time
                  description: The start date of the mandate
                  example: '2024-01-01T00:00:00Z'
                externalReference:
                  type: string
                  description: External reference for the mandate
                  example: EXT_REF_12345
                failureReasons:
                  type: array
                  items:
                    type: string
                  description: Array of failure reasons if the mandate was rejected
                  example:
                  - Invalid account details
                  - Insufficient funds
                failureCodes:
                  type: array
                  items:
                    type: string
                  description: Array of failure codes if the mandate was rejected
                  example:
                  - '900002'
                  - '900003'
                mandateReference:
                  type: string
                  description: The mandate reference number
                  example: MANDATE_REF_12345
                rawRequest:
                  type: string
                  description: Raw request data
                  example: '{"mandateId":"12345","accountDetails":{...}}'
                rawResponse:
                  type: object
                  description: Raw response data from the bank
                  example:
                    status: SUCCESS
                    mandateId: '12345'
                    responseCode: '0000'
                submittedAt:
                  type: string
                  format: date-time
                  description: The date when the mandate was submitted
                  example: '2024-01-01T00:00:00Z'
      responses:
        '200':
          description: Successfully updated DebiCheck Mandate
          content:
            application/json:
              schema:
                $ref: '#/paths/~1payment-methods~1debicheck-mandates/post/responses/201/content/application~1json/schema'
  /payment-methods/debicheck-mandates:
    post:
      operationId: create-debicheck-mandate
      summary: Create DebiCheck Mandate
      description: Creates a new DebiCheck mandate for a policy.
      tags:
      - Payment Methods
      x-additional-tags:
      - Billing & payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - policyId
              - providerType
              - debicheckAuthenticationType
              properties:
                policyId:
                  type: string
                  format: uuid
                  description: The ID of the policy to create the mandate for
                  example: 00000000-0000-0000-0000-00000000000a
                providerType:
                  type: string
                  enum:
                  - nedbank
                  - external
                  description: Provider type for the DebiCheck mandate
                  example: nedbank
                debicheckAuthenticationType:
                  type: string
                  enum:
                  - REAL TIME
                  - BATCH
                  - PREAUTH
                  description: Authentication type for the DebiCheck mandate
                  example: BATCH
      responses:
        '201':
          description: Successfully created DebiCheck Mandate
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The unique identifier of the DebiCheck mandate.
                  policy_id:
                    type: string
                    format: uuid
                    description: The unique identifier of the policy.
                  payment_method_id:
                    type: string
                    format: uuid
                    description: The unique identifier of the payment method.
                  status:
                    type: string
                    enum:
                    - pending
                    - submitted
                    - processing
                    - active
                    - rejected
                    - suspended
                    - cancelled
                    - no_response
                    description: The status of the DebiCheck mandate.
                  submitted_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The date and time the mandate was submitted.
                  authorized_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The date and time the mandate was authorized.
                  rejected_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The date and time the mandate was rejected.
                  cancelled_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The date and time the mandate was cancelled.
                  mandate_reference:
                    type: string
                    nullable: true
                    description: The mandate reference.
                  external_reference:
                    type: string
                    nullable: true
                    description: The external reference for the mandate.
                  failure_reasons:
                    type: array
                    items:
                      type: string
                    nullable: true
                    description: Reasons for failure.
                  failure_codes:
                    type: array
                    items:
                      type: string
                    nullable: true
                    description: Failure codes.
                  contract_reference:
                    type: string
                    nullable: true
                    description: The contract reference.
                  installment_occurance:
                    type: string
                    nullable: true
                    description: The installment occurrence.
                  frequency:
                    type: string
                    nullable: true
                    description: The frequency of the mandate.
                  start_date:
                    type: string
                    format: date-time
                    nullable: true
                    description: The start date of the mandate.
                  amount:
                    type: number
                    nullable: true
                    description: The amount of the mandate.
                  max_collection_amount:
                    type: number
                    nullable: true
                    description: The maximum collection amount.
                  collection_day:
                    type: integer
                    nullable: true
                    description: The collection day.
                  first_collection_date:
                    type: string
                    format: date-time
                    nullable: true
                    description: The first collection date.
                  first_collection_amount:
                    type: number
                    nullable: true
                    description: The first collection amount.
                  created_at:
                    type: string
                    format: date-time
                    description: The date and time the mandate was created.
                  updated_at:
                    type: string
                    format: date-time
                    description: The date and time the mandate was last updated.
                  policy:
                    $ref: '#/components/schemas/policy'
                    nullable: true
                  payment_method:
                    $ref: '#/components/schemas/payment-method'
                    nullable: true
                  debicheck_mandate_batch_id:
                    type: string
                    format: uuid
                    nullable: true
                    description: The unique identifier of the DebiCheck mandate batch.
                  provider_type:
                    type: string
                    enum:
                    - nedbank
                    - external
                    description: The provider type for the DebiCheck mandate.
                required:
                - id
                - policy_id
                - payment_method_id
                - status
                - created_at
                - updated_at
                - provider_type
components:
  schemas:
    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:
      

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