# Debt Account Requests

Debt Account Requests notify Customer via sms or email about a payment, a payment plan or a settlement offer for a Debt Account. The message contains a Customer Session link to the Portal.

Each request returns the Customer Session. If type is omitted, no message is sent and you can send the link to the Customer yourself.

Requests for a child Debt Account are created for its Parent Debt Account. See Debt Account Nesting.

# Create Payment Request

You can create a payment request that notifies Customer via sms or email about the request. Customer can pay any amount starting from min_payment_amount.

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

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/charges/request \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d type="email" \
 -d email="example@example.com" \
 -d min_payment_amount=5000 \
 -d expiration_date="2026-12-01"

# Parameters

min_payment_amount required|number:cents|min:100

It specifies minimum amount for a payment. It is saved as Debt Account's min_payment_amount Rule.

expiration_date required|date

This parameter sets an expiration date for the session link, after which it becomes invalid and cannot be used.

type optional|in:sms,email

How to send the message. Use sms (sent to the recipient's phone) or email (sent to the recipient's email). Leave it out to only create the link and send it to the Customer yourself.

email required if type is email or save_email is true|email

The email parameter is required when the type parameter is set to email or save_email is true.

phone required if type is sms or save_phone is true|string|US

The phone parameter is required when the type parameter is set to sms or save_phone is true.

save_email optional|boolean

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

save_phone optional|boolean

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

# Other validations

If type is provided, the Payment Request notification must be enabled in Console Settings.
If type is provided, Customer cannot be unsubscribed from payment requests via that type.
If type is sms, Organization must have a phone number to send messages.

# Returns

A json with data property that contains created customer session object.

{
  "id": "string",
  "portal_url": "url",
  "short_url": "url",
  "return_url": null,
  "expiration_return_url": null,
  "valid_till": "2026-12-01 00:00:00"
}

# Create Payment Plan Request

You can create a payment plan request that notifies Customer via sms or email about the request. A Payment Plan with status pending is created. Customer chooses the payment amount, starting from min_payment_amount, and accepts the Payment Plan in the Portal.

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

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/payment-plans/request \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d type="sms" \
 -d phone="2015550123" \
 -d frequency="monthly" \
 -d start_date="2026-12-01" \
 -d min_payment_amount=10000 \
 -d expiration_date="2026-11-25"

# Parameters

frequency required|string

Specifies the periodicity of payments.

Supported frequencies:

weekly
every_other_week
monthly
last_of_month

start_date required|date

It must be a date at least 1 day after enrollment and within the number of days defined in the payment_plan_max_days_until_start_date rule, which defaults to 31.

min_payment_amount required|number:cents|min:100

It specifies minimum amount for a payment. It is saved as Debt Account's min_payment_amount Rule.

expiration_date required|date

This parameter sets an expiration date for the session link, after which it becomes invalid and cannot be used.

type optional|in:sms,email

How to send the message. Use sms (sent to the recipient's phone) or email (sent to the recipient's email). Leave it out to only create the link and send it to the Customer yourself.

email required if type is email or save_email is true|email

The email parameter is required when the type parameter is set to email or save_email is true.

phone required if type is sms or save_phone is true|string|US

The phone parameter is required when the type parameter is set to sms or save_phone is true.

save_email optional|boolean

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

save_phone optional|boolean

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

# Other validations

Debt Account status must be active.
Debt Account cannot have Payment Plan with status pending or active.
Debt Account must have a payment gateway.
If type is provided, the Payment Plan Request notification must be enabled in Console Settings.
If type is provided, Customer cannot be unsubscribed from payment plan requests via that type.
If type is sms, Organization must have a phone number to send messages.

# Returns

A json with data property that contains created customer session object.

payment_plan contains the created Payment Plan.

{
  "id": "string",
  "portal_url": "url",
  "short_url": "url",
  "return_url": null,
  "expiration_return_url": null,
  "valid_till": "2026-11-25 00:00:00",
  "payment_plan": {
    "id": "string",
    "status": "pending",
    "plan_type": "standard",
    "frequency": "monthly",
    "start_date": "2026-12-01",
    "amount": null,
    "enrolled_at": null,
    "charges": [],
    ...
  }
}

# Create Settlement Offer Request

You can create a settlement offer request that notifies Customer via sms or email about the request. Customer can accept the settlement offer of the Debt Account in the Portal. If is_custom_offer is true, a custom settlement offer is created for this request instead.

A pending custom settlement offer created by a previous request is closed.

This endpoint requires the Accept Settlement Offers From Api permission. Contact Tratta to enable it for your API user.

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

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/settlement-offers/request \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d type="email" \
 -d email="example@example.com" \
 -d expiration_date="2026-12-01" \
 -d is_custom_offer=true \
 -d discount_percentage=20

# Parameters

expiration_date required|date|after:today

This parameter sets an expiration date for the session link and the custom settlement offer, after which they become invalid and cannot be used.

is_custom_offer optional|boolean

Specifies whether to create a custom settlement offer for this request. Default is false.

discount_percentage required with is_custom_offer, 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 with is_custom_offer, 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.

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.

type optional|in:sms,email

How to send the message. Use sms (sent to the recipient's phone) or email (sent to the recipient's email). Leave it out to only create the link and send it to the Customer yourself.

email required if type is email or save_email is true|email

The email parameter is required when the type parameter is set to email or save_email is true.

phone required if type is sms or save_phone is true|string|US

The phone parameter is required when the type parameter is set to sms or save_phone is true.

save_email optional|boolean

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

save_phone optional|boolean

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

# Other validations

If is_custom_offer is not true, Debt Account must have a settlement offer that matches it.
If is_custom_offer is true, Organization's custom_settlement_enabled Rule must be on.
If is_custom_offer is true, Debt Account status must be active.
If is_custom_offer is true, Debt Account cannot have an accepted settlement offer.
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.
If type is provided, the Settlement Offer Request notification must be enabled in Console Settings.
If type is provided, Customer cannot be unsubscribed from settlement offer requests via that type.
If type is sms, Organization must have a phone number to send messages.

# Returns

A json with data property that contains created customer session object.

{
  "id": "string",
  "portal_url": "url",
  "short_url": "url",
  "return_url": null,
  "expiration_return_url": null,
  "valid_till": "2026-12-01 23:59:59"
}

← Payment Plans Payment Methods →