The Payment Methods API from Root Insurance — 7 operation(s) for payment methods.
openapi: 3.1.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:
payment-details:
type: object
description: Details of the account into which the payout should be made.
required:
- type
- details
properties:
type:
type: string
description: The type of account into which the payout should be made. For a beneficiary, this must be `eft`.
enum:
- eft
- card
details:
type: object
description: The bank account details.
required:
- bank_name
- branch_code
- account_type
- account_number
properties:
bank_name:
$ref: '#/components/schemas/bank-name'
branch_code:
type: string
description: The branch code for the account.
account_type:
type: string
description: The account type.
enum:
- cheque_account
- savings
account_number:
type: string
description: The account number.
payment-charge-type:
type: string
description: Variable charges are applied as a proportion of the total payment amount. Fixed charges are applied as an absolute currency value in cents. The `balance` is the balance of the payment total after all charges have been applied.
enum:
- fixed
- variable
- balance
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.
status:
$ref: '#/components/schemas/policy-status'
policyholder_id:
type: string
description: Must be a UUID. The system identifier of the policy's policyholder.
package_name:
type: string
description: The insurance package name.
sum_assured:
type: integer
description: The amount, in cents, of the maximum value insured.
monthly_premium:
type: integer
description: The total monthly premium, in cents, that will be billed to the policyholder.
billing_amount:
type: integer
description: The amount, in cents, that will be billed on the next billing run.
balance:
type: integer
description: The amount, in cents, that is owed on the policy. If the policyholder makes an adhoc payment to the policy, the amount is credited to this balance. If the policyholder defaults on a payment, it is subtracted from the balance. If the balance is found negative during the next billing run, the amount is added to the monthly premium, else the monthly premium is subtracted from the balance and the remainder is charged.
billing_day:
type:
- integer
- 'null'
description: '`null` is allowed. The day of month on which the policy is billed. Should be between 1 and 31, or `null`. If it falls on a day that does not exist in the month (for example, 31 in February) the policy will be billed on the last day of the month. Setting this value to 31 will ensure that the policy is billed on the last day of every month.'
billing_frequency:
type: string
description: The frequency at which the policy is billed. One of [`monthly`, `yearly`, `once_off`]. See the [billing settings](https://docs.rootplatform.com/docs/billing-settings#billing-frequency) guide for more details on the billing frequency.
next_billing_date:
type: string
format: date-time
description: The next date the policy is due to be billed.
currency:
type: string
description: The currency code of the policy.
beneficiaries:
description: An array of beneficiaries, or "null".
oneOf:
- $ref: '#/components/schemas/beneficiaries'
- type: 'null'
covered_people:
type:
- array
- 'null'
items:
type: object
description: '`null` is allowed. An array of covered people added to the policy.'
base_premium:
type: integer
description: The amount, in cents, of the minimum allowed monthly premium fee. This includes risk pricing and platform fees.
claim_ids:
type: array
items:
type: string
description: An array of claim ids of the claims linked to the policy.
complaint_ids:
type: array
items:
type: string
description: An array of complaint ids of the complaints linked to the policy.
start_date:
type: string
format: date-time
description: Once the policy reaches its start date, cover commences and regular collection attempts can run against the policy (provided it has an `active` status). See the [Managing policies](https://docs.rootplatform.com/docs/policy-administration#policy-lifecycle) guide for more details on the policy li
# --- 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