The Payments API from Root Insurance — 6 operation(s) for payments.
openapi: 3.1.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:
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.'
beneficiaries:
type: array
description: '`null` is allowed. An array of beneficiaries. If null, the default beneficiary may be the policyholder if enabled in the product module settings. Some product modules may require adding beneficiaries to a policy for claims to be processed.'
items:
type: object
description: Details for a single beneficiary.
required:
- beneficiary_id
- relationship
- percentage
properties:
beneficiary_id:
type: string
description: Must be a UUID. The unique identifier of the beneficiary.
policyholder_id:
type: string
description: Must be a UUID. The unique identifier of the policyholder. Only relevant if `relationship` is `policyholder`.
type:
type: string
description: The type of beneficiary.
enum:
- individual
- company
default: individual
first_name:
type: string
description: The beneficiary's first name.
last_name:
type: string
description: The beneficiary's last name.
title:
type: string
description: The beneficiary's title.
enum:
- mr
- mrs
- miss
- mx
- sir
- dr
- adv
- ms
- prof
gender:
type: string
description: The beneficiary's gender.
enum:
- male
- female
id:
type: object
description: (Individual beneficiaries only) The beneficiary's identification number, type and country.
properties:
type:
type: string
description: The beneficiary's identification type.
enum:
- id
- passport
- custom
number:
type: string
description: Depending on the type selected, either an ID number, passport number or custom identifier.
country:
type: string
description: The [ISO Alpha-2](http://www.nationsonline.org/oneworld/country_code_list.htm) country code of the `number`.
required:
- type
- number
- country
date_of_birth:
type:
- string
- 'null'
format: date
description: '`null` is allowed. The beneficiary''s date of birth.'
percentage:
type: integer
description: An integer representing the percentage of a claim payout that the beneficiary should receive. Note that the percentages across all beneficiaries should add up to 100%.
cellphone:
$ref: '#/components/schemas/cellphone-string'
email:
type: string
description: The beneficiary's email address.
relationship:
$ref: '#/components/schemas/beneficiary-relationship'
company_name:
type: string
description: The name of the company that the beneficiary represents. Required when `type = company`.
registration_number:
type: string
description: The company's registration number. Required when `type = company`.
payment_details:
$ref: '#/components/schemas/payment-details'
example:
first_name: Jared
last_name: Dunn
id:
type: id
number: '8704094800082'
country: ZA
percentage: 100
relationship: cousin_or_relative
example:
- first_name: Jared
last_name: Dunn
id:
type: id
number: '8704094800082'
country: ZA
percentage: 100
relationship: cousin_or_relative
payment-status:
type: string
enum:
- submitted
- pending
- processing
- successful
- failed
- cancelled
description: The status to which to create the payment.
payment-type:
type: string
description: The type of the payment being created.
enum:
- premium
- reversal
- claim_payout
- premium_refund
- other
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
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.
'
collection-type:
type: string
description: The collection type of the payment being created.
enum:
- debit_order_same_day
- debit_order_two_day
- debit_order_one_day
- debit_order_debicheck
- card
- external
- collection_module
- other
payment-create-async:
allOf:
- $ref: '#/components/schemas/payment-create'
- type: object
required:
- policy_id
properties:
policy_id:
type: string
description: Id of the policy the payment is for. Must be UUID.
example:
status: successful
description: Monthly premium
payment_type: premium
amount: 1800
payment_date: '2022-09-08T00:00:00Z'
external_reference: B
collection_type: debit_order_same_day
policy_id: 6ae5329f-d286-4d64-9345-af93eb03520c
payment-create:
type: object
required:
- amount
- status
- description
- payment_type
- payment_date
- collection_type
- payment_method_id
properties:
status:
$ref: '#/components/schemas/payment-status'
payment_method_id:
type: string
description: Payment method id of the payment being created. Must be a UUID.
payment_type:
$ref: '#/components/schemas/payment-type'
premium_type:
$ref: '#/components/schemas/premium-type'
amount:
type: number
description: The payment amount. Required when `retry_of` is not provided; otherwise forbidden.
description:
type: string
description: Description of the payment being submitted. Required when `retry_of` is not provided; otherwise forbidden.
payment_date:
type: string
format: date-time
description: Date the payment was created.
finalized_at:
type: string
format: date-time
description: Date the payment was finalized. Required when `status` is `failed` or `successful`.
collection_type:
$ref: '#/components/schemas/collection-type'
billing_date:
type: string
format: date-time
description: Date the payment should be processed.
external_reference:
type: string
description: Unique external reference of the payment.
retry_of:
type: string
description: Original payment id of the payment being retried. Must be a UUID.
failure_reason:
type: string
description: A description of the reason the payment failed. Required if `status` is `failed`, forbidden otherwise.
failure_action:
$ref: '#/components/schemas/failure-action'
failure_code:
type: string
description: Optional if `status` is `failed`, forbidden otherwise. The failure error code.
example:
status: successful
description: Monthly premium
payment_type: premium
premium_type: pro_rata
amount: 1800
payment_date: '2022-09-08T00:00:00Z'
external_reference: B23423
collection_type: debit_order_same_day
finalized_at: '2022-09-08T00:00:00Z'
billing_date: '2022-09-08T00:00:00Z'
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 lifecycle.
end_date:
type: string
format: date-time
description: When the policy reaches its end date, its status will change to `expired`. Cover and collections will cease. Policies with no end date do not expire.
current_version:
type:
- integer
- 'null'
description: '`null` is allowed. The current policy schedule version.'
schedule_file_id:
type:
- string
- 'null'
description: '`null` is allowed. Object ID of the policy document.'
policy_schedule_uri:
type:
- string
- 'null'
description: URI to the policy document in PDF format.
terms_file_id:
type:
- string
- 'null'
description: '`null` is allowed. Attachment ID of the policy terms document.'
terms_uri:
type:
- string
- 'null'
description: URI to the terms document in PDF format.
supplementary_terms_files:
type: array
description: Supplementary terms files associated with the policy.
items:
type: object
properties:
supplementary_terms_file_id:
type: string
description: Attachment ID of the supplementary terms document.
type:
type: string
description: The supplementary terms file type, as specified in the product module settings.
uri:
type: string
description: URI to the supplementary terms document in PDF format.
policy_welcome_letter_file_id:
type:
- string
- 'null'
description: '`null` is allowed. Object ID of the welcome letter.'
policy_welcome_letter_uri:
type:
- string
- 'null'
description: '`null` is allowed. URI to the welcome let
# --- 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