Tratta Docs

# Settlement Offers

Settlement offers allow customers to pay off their debt at a discount. You can accept the settlement offer of a Debt Account or a custom settlement offer for Customer. To let Customer accept a settlement offer in the Portal, use Create Settlement Offer Request.

Settlement offers for a child Debt Account are accepted for its Parent Debt Account. See Debt Account Nesting.

# Settlement Offer

If a settlement offer matches a Debt Account, it is returned as settlement_offer in Get Debt Account and Debt Account Lookup. It is not returned in List Debt Accounts.

{
  "id": "58b3b585-ebf4-4b44-9c1d-591fd5cd9965",
  "name": "Settlement Offer",
  "status": "active",
  "description": null,
  "base_on": "current_balance",
  "base_on_unit_type": "cents",
  "matching_discount": {
    "id": "a8c7766f-382a-4467-b0e8-c4ae1c676110",
    "from_current_balance": null,
    "to_current_balance": null,
    "discount_percentage": "20.00",
    "months_period": 2,
    "periods": [
      {
        "id": "0c5854d0-d772-4dd3-95ba-e79d54efdb48",
        "discount_percentage": "20.00",
        "months_period": 1,
        "created_at": "2026-11-09 17:59:56",
        "updated_at": "2026-11-09 17:59:56"
      },
      {
        "id": "dc335ceb-cb81-4178-9818-0906454e98f8",
        "discount_percentage": "19.00",
        "months_period": 2,
        "created_at": "2026-11-09 17:59:56",
        "updated_at": "2026-11-09 17:59:56"
      }
    ],
    "created_at": "2026-11-09 17:59:56",
    "updated_at": "2026-11-09 17:59:56"
  },
  "settlement_offer_start_date": null,
  "settlement_offer_end_date": null,
  "created_at": "2026-11-09T17:59:56.000000Z",
  "updated_at": "2026-11-09T17:59:56.000000Z"
}

matching_discount

Discount that matches the Debt Account. Each of its periods can be accepted with Accept Settlement Offer. A period with months_period 1 is paid in a single payment, a longer period in a Payment Plan. discount_percentage is the discount of the balance in base_on in percent.

base_on

Balance the discount is calculated from. base_on holds one of two things:

  • The text current_balance. The discount is calculated from Debt Account's current_balance.
  • The name of a Debt Account metadata field. The discount is calculated from the value of that field, in base_on_unit_type (cents or dollars). If Debt Account does not have that field, current_balance is used.

For example, a 20% discount based on a metadata field of 8000 cents settles a Debt Account with current_balance 10000 for 6400 cents. The accepted settlement offer then has discount_percentage 36.00, the discount of current_balance in percent.

settlement_offer is not returned if Debt Account status is not active or Debt Account already has an accepted settlement offer.

# Accept Settlement Offer

You can accept a period of the settlement offer that matches a Debt Account. If start_date is today, Customer is charged immediately. Otherwise a charge is scheduled, or a Payment Plan if months_period of the period is more than 1.

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

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/settlement-offers \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d settlement_offer_discount_period_id="dc335ceb-cb81-4178-9818-0906454e98f8" \
 -d start_date="2026-12-01" \
 -d frequency="monthly" \
 -d email="example@example.com" \
 -d card[card_holder]="Card Holder" \
 -d card[card_number]="4242424242424242" \
 -d card[card_expiration_month]="12" \
 -d card[card_expiration_year]="27" \
 -d card[card_security_code]="123"

# Parameters

settlement_offer_discount_period_id required|exists

Specifies the id of a period in matching_discount of the Settlement Offer.

start_date required|date

Date of the first payment. The value must be a date with Y-m-d format. A single payment can start today, a payment plan at least 1 day after today. It must be at least the number of days defined in the min_days_until_start_date rule after today. It must be within the number of days defined in the settlement_offer_max_days_until_start_date rule, or within the month if the settlement_offer_schedulable_by_end_of_month rule is enabled.

frequency required if months_period is more than 1|string

Specifies the periodicity of payments.

Supported frequencies:

  • weekly
  • every_other_week
  • monthly
  • last_of_month

email required if save_email is true|email

Email address where the confirmation of the payment is sent.

save_email optional|boolean

Specifies whether to save email as Customer's email. Default is false. If it is true, email is required.

payment_method_id required without card/ach|exists

Specifies the UUID of the existing payment method.

card json object with parameters

  • card_holder required without payment_method_id/ach
  • card_number required without payment_method_id/ach|valid card number
  • card_expiration_month required without payment_method_id/ach|numeric|between:1,12
  • card_expiration_year required without payment_method_id/ach|last 2 digits of a year
  • card_security_code optional
  • card_postal_code optional|5 digits

ach json object with parameters

  • account_holder required without payment_method_id/card

  • account_type required without payment_method_id/card|in:checking, savings

    Checking or Savings account type.

  • ownership_type required without payment_method_id/card|in:personal, business

    Specifies the ownership type of the account.

    If business is selected, the SEC code will be set to CCD. Otherwise, WEB will be used.

  • routing_number required without payment_method_id/card|valid routing number

  • account_number required without payment_method_id/card|min:4|max:17

  • account_zip required without payment_method_id/card|5 digits

    Specifies the Postal code of the account.

  • account_state required without payment_method_id/card

remember_payment_method optional|boolean

Specifies whether to save card or ach as Customer's payment method. Default is false.

billing_address_id optional|exists

Specifies the UUID of the billing address.

billing_address json object with parameters

  • name optional|string
  • city optional|string
  • state optional|string
  • postal_code required with billing address object|5 digits
  • country optional|string
  • line1 optional|string
  • line2 optional|string
  • is_primary optional|boolean

# Other validations

  • The period must belong to the settlement offer that matches Debt Account.
  • Debt Account status must be active.
  • Debt Account cannot have an accepted settlement offer.
  • Debt Account must have a payment gateway.
  • Debt Account cannot have Payment Plan with status active, unless Organization allows to replace it with a settlement offer. The Payment Plan is then canceled.
  • Card network and card type must be allowed by Organization's Rules.
  • Bank account cannot be blocked, and Customer cannot be blocked from ACH payments.
  • If a matched fee applies, billing_address_id or billing_address with state and postal_code is required.

# Returns

A json with data property that contains created accepted settlement offer object.

If the payment fails, an error is returned and the settlement offer is not accepted.

immediate charge

When start_date is today. charges contains the Charge.

{
  "settlement_offer": {
    "id": "58b3b585-ebf4-4b44-9c1d-591fd5cd9965",
    "name": "Settlement Offer",
    "status": "active",
    "description": null,
    "base_on": "current_balance",
    "base_on_unit_type": "cents",
    "created_at": "2026-11-09T17:59:56.000000Z",
    "updated_at": "2026-11-09T17:59:56.000000Z"
  },
  "charges": [
    {
      "id": "437bd92a-4a82-457e-95ae-58b4540dce2c",
      "reference_number": 123456,
      "payment_method_type": "card",
      "amount": 80000,
      "total_amount": 80000,
      "payment_date": "11/09/2026",
      "success": true,
      "source": "API",
      "source_name": "1",
      "created_at": "2026-11-09 17:59:56",
      "updated_at": "2026-11-09 17:59:56"
    }
  ],
  "scheduled_charge": null,
  "payment_plan": null,
  "has_payment_plan": false,
  "name": "Settlement Offer",
  "discount_percentage": "20.00",
  "discount": 20000,
  "months_period": 1,
  "amount": 100000,
  "discounted_amount": 80000,
  "total_amount": 80000,
  "status": "completed",
  "created_at": "2026-11-09 17:59:56",
  "updated_at": "2026-11-09 17:59:56"
}

payment plan

When months_period is more than 1. payment_plan contains the created Payment Plan.

{
  "settlement_offer": {
    "id": "58b3b585-ebf4-4b44-9c1d-591fd5cd9965",
    "name": "Settlement Offer",
    "status": "active",
    "description": null,
    "base_on": "current_balance",
    "base_on_unit_type": "cents",
    "created_at": "2026-11-09T17:59:56.000000Z",
    "updated_at": "2026-11-09T17:59:56.000000Z"
  },
  "charges": [],
  "scheduled_charge": null,
  "payment_plan": {
    "id": "41429b3b-2ad7-46f0-9248-358187ceab78",
    "plan_type": "standard",
    "checkout_type": "Settlement Payment Plan",
    "frequency": "monthly",
    "start_date": "2026-11-12",
    "end_date": "2026-12-12",
    "amount": 40500,
    "status": "active",
    "charges": [
      {
        "id": "7c123d9b-ef1d-4e79-8c41-48b70dc8ecbd",
        "charge_date": "2026-11-12",
        "amount": 40500,
        "status": "pending",
        "scheduled": true
      },
      {
        "id": "122bea92-fecc-4928-a402-296a4885f428",
        "charge_date": "2026-12-12",
        "amount": 40500,
        "status": "pending",
        "scheduled": true
      }
    ]
  },
  "has_payment_plan": true,
  "name": "Settlement Offer",
  "discount_percentage": "19.00",
  "discount": 19000,
  "months_period": 2,
  "amount": 100000,
  "discounted_amount": 81000,
  "total_amount": 81000,
  "status": "active",
  "created_at": "2026-11-09 17:59:56",
  "updated_at": "2026-11-09 17:59:56"
}

# Accept Custom Settlement Offer

You can accept a custom settlement offer for a Debt Account. The custom settlement offer is created for this Debt Account only. If start_date is today, Customer is charged immediately. Otherwise a charge is scheduled, or a Payment Plan if is_payment_plan is true.

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

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/settlement-offers/custom \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d discounted_amount=75000 \
 -d start_date="2026-12-01" \
 -d email="example@example.com" \
 -d payment_method_id="83099bb0-e4e0-42f8-989b-3e2711ab2dcd"

# Parameters

discount_percentage required without discounted_amount|numeric

Discount of Debt Account's current_balance in percent. It must be between Organization's custom_settlement_min_discount_percentage and custom_settlement_max_discount_percentage Rules. It cannot be sent together with discounted_amount.

discounted_amount required without discount_percentage|number:cents

Amount the Customer pays to settle the Debt Account. The discount must be between Organization's custom_settlement_min_discount_percentage and custom_settlement_max_discount_percentage Rules. It cannot be sent together with discount_percentage.

start_date required|date|after_or_equal:today

Date of the first payment. The value must be a date with Y-m-d format. A single payment can start today, a payment plan at least 1 day after today. It must be at least the number of days defined in the min_days_until_start_date rule after today.

is_payment_plan optional|boolean

Specifies whether the Customer pays the custom settlement offer in a payment plan. Default is false.

frequency required if is_payment_plan is true|string

Specifies the periodicity of payments.

Supported frequencies:

  • weekly
  • every_other_week
  • monthly
  • last_of_month

amount required if is_payment_plan is true|number:cents

The amount of single payment plan payment.

email required if save_email is true|email

Email address where the confirmation of the payment is sent.

save_email optional|boolean

Specifies whether to save email as Customer's email. Default is false. If it is true, email is required.

payment_method_id required without card/ach|exists

Specifies the UUID of the existing payment method.

card json object with parameters

  • card_holder required without payment_method_id/ach
  • card_number required without payment_method_id/ach|valid card number
  • card_expiration_month required without payment_method_id/ach|numeric|between:1,12
  • card_expiration_year required without payment_method_id/ach|last 2 digits of a year
  • card_security_code optional
  • card_postal_code optional|5 digits

ach json object with parameters

  • account_holder required without payment_method_id/card

  • account_type required without payment_method_id/card|in:checking, savings

    Checking or Savings account type.

  • ownership_type required without payment_method_id/card|in:personal, business

    Specifies the ownership type of the account.

    If business is selected, the SEC code will be set to CCD. Otherwise, WEB will be used.

  • routing_number required without payment_method_id/card|valid routing number

  • account_number required without payment_method_id/card|min:4|max:17

  • account_zip required without payment_method_id/card|5 digits

    Specifies the Postal code of the account.

  • account_state required without payment_method_id/card

remember_payment_method optional|boolean

Specifies whether to save card or ach as Customer's payment method. Default is false.

billing_address_id optional|exists

Specifies the UUID of the billing address.

billing_address json object with parameters

  • name optional|string
  • city optional|string
  • state optional|string
  • postal_code required with billing address object|5 digits
  • country optional|string
  • line1 optional|string
  • line2 optional|string
  • is_primary optional|boolean

# Other validations

  • Organization's custom_settlement_enabled Rule must be on.
  • If is_payment_plan is true, the payment plan must have more than one payment, and its duration cannot be longer than Organization's custom_settlement_max_length_in_months Rule.
  • Debt Account status must be active.
  • Debt Account cannot have an accepted settlement offer.
  • Debt Account must have a payment gateway.
  • Debt Account cannot have Payment Plan with status active, unless Organization allows to replace it with a settlement offer. The Payment Plan is then canceled.
  • Card network and card type must be allowed by Organization's Rules.
  • Bank account cannot be blocked, and Customer cannot be blocked from ACH payments.
  • If a matched fee applies, billing_address_id or billing_address with state and postal_code is required.

# Returns

A json with data property that contains created accepted settlement offer object.

If the payment fails, an error is returned and the settlement offer is not accepted.

scheduled charge

When start_date is after today. scheduled_charge contains the scheduled charge.

{
  "settlement_offer": {
    "id": "1ed45d26-04ab-456e-9865-d7f98ab6e418",
    "name": "Custom settlement offer for debt account: 123456",
    "status": "disabled",
    "description": null,
    "base_on": "current_balance",
    "base_on_unit_type": "cents",
    "created_at": "2026-11-09T17:59:56.000000Z",
    "updated_at": "2026-11-09T17:59:56.000000Z"
  },
  "charges": [],
  "scheduled_charge": {
    "id": "cdea338f-e353-435e-b1ea-64fd71bc3c6a",
    "payment_method_type": "card",
    "payment_method": {
      "id": "83099bb0-e4e0-42f8-989b-3e2711ab2dcd",
      "type": "card",
      "card_token": {
        "card_holder": "Card Holder",
        "card_number": "4242",
        "expiration_month": "12",
        "expiration_year": "27",
        "card_type": "Visa",
        "card_zip": null
      },
      "is_primary": true,
      "created_at": "2026-11-09 17:59:56"
    },
    "scheduled_at": "2026-11-12",
    "successfully_charged_at": null,
    "amount": 75000,
    "source": "API",
    "source_name": "1",
    "created_at": "2026-11-09 17:59:56",
    "updated_at": "2026-11-09 17:59:56"
  },
  "payment_plan": null,
  "has_payment_plan": false,
  "name": "Custom settlement offer for debt account: 123456",
  "discount_percentage": "25.00",
  "discount": 25000,
  "months_period": 1,
  "amount": 100000,
  "discounted_amount": 75000,
  "total_amount": 75000,
  "status": "active",
  "created_at": "2026-11-09 17:59:56",
  "updated_at": "2026-11-09 17:59:56"
}

← Debt Account Requests →