# Debt Accounts

Debt Accounts represent Debt to be paid off by Customers. You can attach one or more Debt Accounts to single Customer. Debt Account can be attached to Location.

# Debt Account Nesting

We also support nesting of Debt Accounts. This is useful when you want to group multiple Debt Accounts into 1. This allows you to change properties of individual child accounts, while Customer interacts just with the Parent Debt Account. balance and current_balance of Parent is a sum of all Children Debt Accounts. Balance updates made to any child via API result in re-calculation of balance and current_balance of Parent Debt Account.

Debt Account Nesting

# Create Debt Account

POST https://<org-uuid>.production.tratta.io/api/v1/debt-accounts

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d customer_id="customer-uuid" \
 -d balance=10000

# Parameters

customer_id required|string

This can be both Customer id (uuid) generated in Tratta or external Customer id external_id provided in Create Customer.

location_id required|string

This can be both Location id (uuid) generated in Tratta or external Location id external_id provided in Create Location.

location_name required if location_id does not exist / optional|string

Required only if the location location_id you provide does not exist in the system. In that case Location will be automatically created and name is required so we can set it properly. The type will be set by default to original_creditor.

location_type required if location_id does not exist / optional|string

Required only if the location location_id you provide does not exist in the system. In that case Location will be automatically created with provided name and type.

Supported types of Location:

original_creditor
current_creditor
product_type

locations optional /array

This field defines the additonal locations that can be associated to the Debt Account. Checkout the Locations for more information on the Location object.

[
  {
    "name": "Location Name #1",
    // Optional parameters
    "external_id": "AAA",
    "type": "current_creditor",
  },
  {
    "name": "Location Name #2",
    "external_id": "BBB"
  },
  {
    "name": "Location Name #3",
    
  }
]

external_id optional|string

External debt account id generated in the 3rd party application.

parent_external_id optional|string|exists:parent,external_id

External id of debt account that already exists in the system. Debt Account will be added into the system as a child of this parent.

billing_type optional|array

This determines the payment option that will be specified in the return_url property when creating Customer Session.

Signifies the type of payment. Supported values:

partial-payment
full-amount-payment
payment-plan

value	return url
partial-payment	`{portal_url}/partial-payment`
full-amount-payment	`{portal_url}/full-amount-payment`
payment-plan	`{portal_url}/payment-plan`

If nothing is specified, all payment options will be displayed.
If two (2) options are specified, those 2 options will displayed.

external_account_number optional|string

External account number associated with debt account.

payment_plan optional|object

Specifies payment plan that will be created for Debt account. All the fields are optional. If a field is omitted or null Customer will need to complete the Payment Plan configuration step before checkout through Portal UI. frequency must always be passed alongside start_date in request body.

{
  "payment_plan": {
    "frequency": "weekly",
    "start_date": "2021-01-01",
    "amount": "1000"
  }
}

Supported frequencies:

weekly
every_other_week
monthly
last_of_month

Checkout the Payment Plan for more information on the Payment Plan object.

balance required|number:cents

Debt amount placed on Tratta. This amount is usually static. It can be referred to as original balance or full balance owed prior to any payments made.

current_balance optional|number:cents

Refers to the total unpaid amount minus any payments, also referred to as outstanding balance. If current_balance is not specified it will be set to balance value.

metadata optional|key:max:255|value:max:255

Json object of key value pairs for meta data you may want to attach to debt account object.

status

Current state of the debt account. Accepted values:

active : Customer is able to do everything normally.
archived : Account hidden from customer dashboard. Customer cannot make payment to this account.
closed: No payments accepted to this specific account, but customer can login and view.
paid_off : Debt account has been fully paid off.

external_status optional|string

External status of the debt account

rules optional|key:supported_rules|value:supported_rule_values

Rules allow you to override default Debt Account specific logic on the Portal. For example, adding min_payment_amount as a rule when creating the Debt Account, overrides the default Minimum Payment Amount, with your desired value.

rule key	rule value	note
`min_payment_amount`	`numeric\|min:100`	value is in `cents`

{
  "rules": {
    # Minimum Payment Amount must be at least $5.00
    "min_payment_amount": 500
  }
}

# Returns

A json with data property that contains created debt account object.

{
  "id": "string",
  "external_id": "string",
  "parent_external_id": "string",
  "customer": "object",
  "billing_type": "array",
  "balance": "float",
  "current_balance": "float",
  "external_company_id": "string",
  "created_at": "timestamp",
  "rules": "",
  "location": "object",
  "locations": "array",
  "transactions": "array",
  "payment_plan": "object",
  "charges": "array",
  "external_account_number": "string",
  "external_status": "string",
  "location": "object",
  "status": "string",
  "rules": {
    "min_payment_amount": "100"
  },
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Update Debt Account

PUT https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d customer_id="customer-uuid" \
 -d balance=10000
 -X PUT

# Parameters

external_id optional|string

External debt account id generated in the 3rd party application.

parent_external_id optional|string|exists:parent,external_id

External id of debt account that already exists in the system. Debt Account will be set as a child of this parent.

location_id sometimes|string

This can be both Location id (uuid) generated in Tratta or external Location id external_id provided in Create Location.

location_name required if location_id does not exist / optional|string

location_type required if location_id does not exist / optional|string

Required only if the location location_id you provide does not exist in the system. In that case Location will be automatically created with provided name and type.

Supported types of Location:

original_creditor
current_creditor
product_type

locations optional /array

This field defines the additonal locations that can be associated to the Debt Account. Checkout the Locations for more information on the Location object.

[
  {
    "name": "Location Name #1",
    // Optional parameters
    "external_id": "AAA",
    "type": "current_creditor",
  },
  {
    "name": "Location Name #2",
    "external_id": "BBB"
  },
  {
    "name": "Location Name #3",
    
  }
]

billing_type optional|array

Signifies the type of payment. Accepted values:

partial-payment
full-amount-payment
payment-plan

external_account_number optional|string

External account number associated with debt account.

balance required|number:cents

Debt amount placed on Tratta. This amount is usually static. It can be referred to as original balance or full balance owed prior to any payments made.

current_balance optional|number:cents

Refers to the total unpaid amount minus any payments, also referred to as outstanding balance. If current_balance is not specified it will be set to balance value.

metadata optional|key:max:255|value:max:255

Key value pairs can be updated, when you PUT to the key a different value. When you PUT an empty value to existing key, it will be deleted. When you put and empty value to whole metadata, all of the metadata associated with debt account object will be deleted.

status

Current state of the debt account. Accepted values:

active : Customer is able to do everything normally.
archived : Account hidden from customer dashboard. Customer cannot make payment to this account.
closed: No payments accepted to this specific account, but customer can login and view.
paid_off : Debt account has been fully paid off.

🚧 Status effects are currently Work in progress.

external_status optional|string

External status of the debt account

rules optional|nullable|key:supported_rules|value:supported_rule_values

Rules can be updated, when you PUT to the key a different value. When you PUT a null value to an existing key, it will be deleted. When you put a null value to whole rules, all of the rules associated with debt account object will be deleted.

# Returns

A json with data property that contains created debt account object.

{
  "id": "string",
  "external_id": "string",
  "parent_external_id": "string",
  "customer": "object",
  "billing_type": "array",
  "balance": "float",
  "current_balance": "float",
  "external_company_id": "string",
  "created_at": "timestamp",
  "rules": "",
  "location": "object",
  "locations": "array",
  "transactions": "array",
  "payment_plan": "object",
  "charges": "array",
  "external_account_number": "string",
  "external_status": "string",
  "location": "object",
  "status": "string",
  "rules": {
    "min_payment_amount": "100"
  },
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Get Debt Account

GET https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

id required_if:external_id missing|string

Uuid of debt account provided from Tratta when Creating Debt Account object. This url parameter is required only if the external_id wasn't provided instead.

external_id required_if:id missing|string

External id of debt account provided by you through external_id parameter when Creating Debt Account object. This url parameter is required only if the id wasn't provided instead.

# Returns

A json with data property that contains created debt account object.

{
  "id": "string",
  "external_id": "string",
  "parent_external_id": "string",
  "customer": "object",
  "billing_type": "array",
  "balance": "float",
  "current_balance": "float",
  "external_company_id": "string",
  "created_at": "timestamp",
  "rules": "",
  "location": "object",
  "locations": "array",
  "transactions": "array",
  "payment_plan": "object",
  "charges": "array",
  "external_account_number": "string",
  "external_status": "string",
  "location": "object",
  "status": "string",
  "rules": {
    "min_payment_amount": "100"
  },
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# List Debt Accounts

GET https://<org-uuid>.production.tratta.io/api/v1/debt-accounts

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Returns

A json with data property that contains array of debt account objects.

{
  "id": "string",
  "external_id": "string",
  "parent_external_id": "string",
  "customer": "object",
  "billing_type": "array",
  "balance": "float",
  "current_balance": "float",
  "external_company_id": "string",
  "created_at": "timestamp",
  "rules": "",
  "location": "object",
  "locations": "array",
  "transactions": "array",
  "payment_plan": "object",
  "charges": "array",
  "external_account_number": "string",
  "external_status": "string",
  "location": "object",
  "status": "string",
  "rules": {
    "min_payment_amount": "100"
  },
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Delete Debt Account

DELETE https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id/external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -X DELETE

# Parameters

id required_if:external_id missing|string

Uuid of debt account provided from Tratta when Creating Debt Account object. This url parameter is required only if the external_id wasn't provided instead.

external_id required_if:id missing|string

External id of debt account provided by you through external_id parameter when Creating Debt Account object. This url parameter is required only if the id wasn't provided instead.

# Returns

{
  "success": "boolean"
}

# Debt Account Lookup

GET https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/lookup

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/lookup \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

lookup_flow_type required|string

The type of lookup flow that determines how to match debt accounts.

Accepted values:

phone_ssn_last4 : Lookup using phone number and last 4 digits of Social Security Number.
phone_date_of_birth : Lookup using phone number and date of birth.
phone_postal_code : Lookup using phone number and postal code associated with addresses.
first_name_last_name_ssn_last4 : Lookup using first name, last name, and last 4 digits of Social Security Number.
first_name_last_name_date_of_birth : Lookup using first name, last name, and date of birth.

first_name optional|string

First name of customer.

last_name optional|string

Last name of customer.

phone optional|string

Phone number of customer.

date_of_birth optional|date

Date of birth of customer in the format 1991-12-31

ssn_last4 optional|number

The last 4 digits of customer's Social security number

postal_code optional|digits:5

The postal code associated with the addresses of the customer who owns the debt account.

← Locations Charges →