Create policy payment

post

https://sandbox.uk.rootplatform.com/v1/insurance/policies/{policy_id}/payments

This endpoint validates the input and creates a payment, which will result in a 200 OK successful response, with the created payment in the response.

Path Params

policy_id

string

required

The unique identifier of the policy.

Query Params

idempotency_key

string

To perform an idempotent request, provide the idempotency_key query parameter with the request. An idempotency key is a unique value generated by the client which the platform uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using a V4 UUID, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long.

Body Params

status

string

enum

required

The status to which to create the payment.

Allowed:

payment_method_id

string

required

Payment method id of the payment being created. Must be a UUID.

payment_type

string

enum

required

The type of the payment being created.

Allowed:

premium_type

string

enum

The type of the payment being created.Required when payment_type is premium or reversal, optional when payment_type is premium_refund, forbidden otherwise.

amount

number

required

The payment amount. Required when retry_of is not provided; otherwise forbidden.

description

string

required

Description of the payment being submitted. Required when retry_of is not provided; otherwise forbidden.

payment_date

date-time

required

Date the payment was created.

finalized_at

date-time

Date the payment was finalized. Required when status is failed or successful.

collection_type

string

enum

required

The collection type of the payment being created.

billing_date

date-time

Date the payment should be processed.

external_reference

string

Unique external reference of the payment.

retry_of

string

Original payment id of the payment being retried. Must be a UUID.

failure_reason

string

A description of the reason the payment failed. Required if status is failed, forbidden otherwise.

failure_action

string

enum

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). allow_retry: Generate a retry payment (if enabled in the product module settings). Note: The payment method will be blocked after 4 consecutive failed payments regardless. See the billing settings guide for more details on the number of consecutive payments allowed. This field will be required if status is failed, forbidden otherwise.

Allowed:

failure_code

string

Optional if status is failed, forbidden otherwise. The failure error code.

Response

200Success