Payment instructions
Once payments have been created and batched on Root, the instructions need to be delivered to your system. To achieve this, you need to define a transformation template that describes the fields and value formats that your system expects, as well as the delivery method that needs to be used, such as JSON over HTTPS, CSV over SFTP or CSV over S3.
We highly recommend queueing payment instructions when received, before processing them.
Payment data transformation before delivery
During the process of sending payment batches to your system, Root runs a transformation process on the individual payments. This allows you to define how the data should be structured before it arrives.
The transformation template is defined as an export template and consumes the Payment Object. Note the export_template_id for later configuration of the delivery method.
To set up an export template, navigate to Settings > Exports, choose Actions and Create template. Define the fields that you would like to have included in the payment batches, such as payment_id, policy_id, amount, etc.
Do not define any filters, the backend for this framework will automatically include all pending records for submission.
Example template setup:
| Field name | Definition |
|---|---|
| payment_id | {{ payment_id }} |
| policyholder_id | {{ policyholder_id }} |
| policy_id | {{ policy_id }} |
| amount | {{ amount }} |
| billing_date | {{ billing_date }} |
Delivery: JSON over HTTPS (incoming webhook)
Use this method to deliver the payment instructions as batches to an HTTPS endpoint on your system (also known as web-services).
Root will send a POST request per payment batch with the JSON payload conforming to the export template that you defined.
| Setting | Definition |
|---|---|
type | String. Delivery method type, in this case ”https”. |
url | String. The URL where the payment instructions needs to be sent to. |
headers | Object. An JSON object that contains the headers to be used in the request. |
streamRequest | Boolean (default false). Set whether the request should be streamed to the URL. |
batchSize | Number (optional). Define a custom batch size to use. If streamRequest is set to true, then this setting is ignored. |
Delivery: CSV over SFTP
For many systems at scale, it’s easier to process batch files that are delivered as CSV files into an SFTP directory. Use this method if you need Root to deliver the payment instructions as batch files into a predefined SFTP environment.
The batch files will be text files that contain comma-separated fields (CSV) with a payment per row, in the format of the export template that you defined.
| Setting | Definition |
|---|---|
type | String. Delivery method type, in this case ”sftp”. |
host | String. The location of the SFTP host. |
port | String. The port to be used on the SFTP host. |
authenticationMethod | Enum (password or private_key). The authentication method used to connect to the host system. |
username | String. The username used for authentication on the host system. |
password | String. The password used for authentication on the host system. This should be set if password authentication is being used. |
privateKey | String. The private key used for authentication on the host system. This should be set if private_key authentication is being used. |
passphrase | String. The passphrase used for authentication on the host system. This should be set if private_key authentication is being used. |
Secure credentials transfer
The Root support team will assist in secure transfer of access credentials and setup of the delivery method.
Delivery: CSV over S3
Payment instructions can be delivered as batch files to a prespecified AWS S3 directory. Use this method if it’s easier for your system to process files that are delivered in the cloud.
The batch files will be text files that contain comma-separated fields (CSV) with a payment per row, in the format of the export template that you defined.
| Setting | Definition |
|---|---|
type | String. Delivery method type, in this case ”s3”. |
region | String. The AWS region of your bucket. |
bucketName | String. The name of your bucket. |
bucketPath | String. The path in your bucket where you would like the batch files delivered. |
accessKeyId | String. The AWS access key ID for Root to securely access your bucket. |
secretAccessKey | String. The AWS secret access key for Root to securely access your bucket. |
Secure credentials transfer
The Root support team will assist in secure transfer of access credentials and setup of the delivery method.
Updated 12 months ago