# 🚧 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.

# Create Debt Account

POST https://api.tratta.io/api/v1/debt-accounts

curl https://api.tratta.io/api/v1/debt-accounts \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d customer_id="customer-uuid" \
 -d settlement_amount=1000

# 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 / 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.

external_id optional|string

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

billing_type optional|array

Signifies the type of payment. Accepted values:

  • one-time
  • scheduled
  • promise-to-pay
  • payment-plan
  • full-payment

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.

{
  "payment_plan": {
    "frequency": "weekly",
    "recurring_day": "monday",
    "amount": "1000"
  }
}

Supported frequencies:

  • weekly
  • every_other_week
  • monthly

Supported weekly and every_other_week recurring days:

  • monday
  • tuesday
  • wednesdy
  • thursday
  • friday
  • saturday
  • sunday

Supported monthly recurring days:

  • 1st
  • 15th
  • last_day

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|less than or equal to balance

Refers to the total unpaid amount minus any payments, also referred to as outstanding balance.

settlement_amount optional|number:cents|less than or equal to current_balance

A debt settlement refers to an agreement reached between a creditor and a borrower in which a reduced payment from the borrower is regarded as full payment. In other words, a debt settlement is a debt reduction agreement reached between a creditor and borrower.

When Debt Account is created, current_balance will equal to balance if current_balance isn't specified. current_balance is always less than or equal to balance.

If settlement_amount offer is specified and hasn't yet expired, this reduced amount if paid is regarded as full payment of the debt. settlement_amount is always less than or equal to current_balance.

For example: If you create Debt Account with $100 balance and no current_balance, then current_balance is $100, but if you later update settlement_amount to $80, reduced payment of $80 will be accepted as full payment of the debt until settlement_amount offer expires.

settlement_amount_due_date optional|ISO8601

Expiration date of the settlement_amount. After this date, settlement_amount is no longer valid.

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.

# Returns

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

{
  "id": "string",
  "customer": "object",
  "billing_type": "array",
  "payment_plan": "object",
  "payments": "array",
  "settlement_amount": "number",
  "settlement_amount_due_date": "ISO8601",
  "external_account_number": "string",
  "location": "object",
  "is_fully_paid": "boolean",
  "is_active": "boolean",
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Update Debt Account

PUT https://api.tratta.io/api/v1/debt-accounts/{id|external_id}

curl https://api.tratta.io/api/v1/debt-accounts/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d customer_id="customer-uuid" \
 -d settlement_amount=1000
 -X PUT

# Parameters


location_id string

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

external_id string

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

billing_type optional|array

Signifies the type of payment. Accepted values:

  • one-time
  • scheduled
  • promise-to-pay
  • payment-plan
  • full-payment

external_account_number string

External account number associated with debt account.

balance 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 number:cents|less than or equal to balance

Refers to the total unpaid amount minus any payments, also referred to as outstanding balance.

settlement_amount number:cents|less than or equal to current_balance

A debt settlement refers to an agreement reached between a creditor and a borrower in which a reduced payment from the borrower is regarded as full payment. In other words, a debt settlement is a debt reduction agreement reached between a creditor and borrower.

When Debt Account is created, current_balance will equal to balance if current_balance isn't specified. current_balance is always less than or equal to balance.

If settlement_amount offer is specified and hasn't yet expired, this reduced amount if paid is regarded as full payment of the debt. settlement_amount is always less than or equal to current_balance.

For example: If you create Debt Account with $100 balance and no current_balance, then current_balance is $100, but if you later update settlement_amount to $80, reduced payment of $80 will be accepted as full payment of the debt until settlement_amount offer expires.

settlement_amount_due_date YYYY-MM-DD

Expiration date of the settlement_amount. After this date, settlement_amount is no longer valid.

metadata 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.

# Get Debt Account

GET https://api.tratta.io/api/v1/debt-accounts/{id|external_id}

curl https://api.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",
  "customer": "object",
  "billing_type": "array",
  "payment_plan": "array",
  "payments": "array",
  "settlement_amount": "number",
  "external_account_number": "string",
  "location": "object",
  "is_fully_paid": "boolean",
  "is_active": "boolean",
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# List Debt Accounts

GET https://api.tratta.io/api/v1/debt-accounts

curl https://api.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",
  "customer": "object",
  "billing_type": "array",
  "payment_plan": "array",
  "payments": "array",
  "settlement_amount": "number",
  "external_account_number": "string",
  "location": "object",
  "is_fully_paid": "boolean",
  "is_active": "boolean",
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Delete Debt Account

DELETE https://api.tratta.io/api/v1/debt-accounts/{id/external_id}

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

# Returns

{
  "success": "boolean"
}