# Payment Plans

Payment plans allow customers to pay down their debt in recurring fashion. You can create payment plan by passing payment_plan parameters when creating a Debt Account.

# Payment Plan

Once a Payment Plan is created for a Debt Account, it will be attached to the resource.

{
  "id": "1234-5678-1234",
  "frequency": "weekly",
  "start_date": "2021-01-01",
  "amount": 1000,
  "rules": {
    "unscheduled_payment_plan_editable": false
  },
  "charges": [{
    "charge_date": "ISO8601",
    "amount": 1000,
    "scheduled": false,
    "charged_at": "ISO8601"
  },...]
}

charges

Charges associated with payment plan. Once customer agrees on Payment Plan, scheduled will be updated to true. Successful charge will be updated with charged_at datetime.

Charges for a payment plan will become available once the customer is enrolled in the plan.

# Create Payment Plan Request

You can create a payment plan request that notifies Customer via sms or email about the request. Message is send using the phone number or email set up through Console and contains a Customer Session link to the Collect.

POST https://<org-uuid>.production.tratta.io/api/v1/payment-plans/request

curl https://<org-uuid>.production.tratta.io/api/v1/payment-plans/request \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d type="email" \
 -d debt_account_external_id="123456" \
 -d frequency="weekly" \
 -d start_date="2023-03-01" \
 -d min_payment_amount="700" \
 -d email="example@example.com" \
 -X POST

# Parameters

type sometimes|in:sms,email

The type parameter specifies the mode of the message and accepts two possible values: sms or email. It is an optional parameter and can be omitted if message delivery is not required.

It can be set as:

sms: The message will be sent via text message to the recipient's phone number.
email: The message will be sent to the recipient's email address.

email sometimes

The email parameter is required only when the type parameter is set to email.

phone sometimes

The phone parameter is required only when the type parameter is set to phone.

frequency required|string

Specified 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 sometimes|numeric

It specifies minimum amount for a payment.

expiration_date sometimes|date

It's required for a customer session link when the type parameter is present. This parameter sets an expiration date for the session link, after which it becomes invalid and cannot be used.

# Other validations

Debt Account status must be active.
Debt Account cannot have Payment Plan with status active.

# Create and Enroll Payment Plan with Payment Method

You can create and scheduled payment plan in a single request.

POST https://<org-uuid>.production.tratta.io/api/v1/payment-plans

curl https://<org-uuid>.production.tratta.io/api/v1/payment-plans \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d debt_account_external_id="123456" \
 -d amount="700" \
 -d frequency="weekly" \
 -d start_date="2023-03-01" \
 -d scheduled_at="2023-03-01" \
 -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]="23" \
 -d card[card_security_code]="123" 
 -X POST

# Parameters

frequency required|string

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

amount required|numeric

The amount of single payment plan payment.

debt_account_external_id required without no account|exists

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

linked_debt_account optional|boolean

Specifies whether the transaction should be associated with a specific debt account or not. It allows you to process a charge without linking it to a particular debt account in the system. If you pass debt_account_external_id with linked_debt_account=false then it will create a charge without linking it to an debt account.

email optional|email

Email address of the customer.

send_email optional|boolean

Specifies whether or not to send the confirmation email to the customer.

payment_method_id required without card/ach|exists

Specifies the UUID of the existing payment method.

card json object with paramters

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 optional in:personal, business

Specifies the ownership type of the account. Default is personal.

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

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

Debt Account status must be active.
Debt Account cannot have Payment Plan with status active.
Payment Plan duration cannot be longer than Organization's payment_plan_max_length_in_months Rule. Default value is 5 years.

# Returns

A json with data property that contains created payment-plan object.

{
  "id": "1234-5678-1234",
  "frequency": "weekly",
  "start_date": "2021-01-01",
  "amount": 1000,
  "rules": {
    "unscheduled_payment_plan_editable": false
  },
  "charges": [{
    "charge_date": "ISO8601",
    "amount": 1000,
    "scheduled": false,
    "charged_at": "ISO8601"
  },...]
}

# Get Payment Plan

GET https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid}

curl https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Update Payment Plan

If payment plan doesn't have any scheduled charges and the rule unscheduled_payment_plan_editable is set to true it can be edited.

PUT https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid}

curl https://<org-uuid>.production.tratta.io/api/v1/payment-methods/{payment-method-uuid} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d frequency="weekly" \
 -d start_date="2021-01-01" \
 -d amount="700"
 -X PUT

# Parameters

frequency required|string

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

amount required|numeric

The amount of single payment plan payment.

# Returns

A json with data property that contains created payment-plan object.

{
  "id": "1234-5678-1234",
  "frequency": "weekly",
  "start_date": "2021-01-01",
  "amount": 1000,
  "rules": {
    "unscheduled_payment_plan_editable": false
  },
  "charges": [{
    "charge_date": "ISO8601",
    "amount": 1000,
    "scheduled": false,
    "charged_at": "ISO8601"
  },...]
}

# Update Payment Plan Status

PATCH https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid}/status

curl https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid}/status \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d status="canceled" \
 -X PATCH

# Parameters

status required|in:canceled

Supported statuses:

canceled

# Returns

A json with data property that contains created payment-plan object.

{
  "id": "1234-5678-1234",
  "frequency": "weekly",
  "start_date": "2021-01-01",
  "amount": 1000,
  "rules": {
    "unscheduled_payment_plan_editable": false
  },
  "charges": [{
    "charge_date": "ISO8601",
    "amount": 1000,
    "scheduled": false,
    "charged_at": "ISO8601"
  },...]
}

# Delete Payment Plan

DELETE https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid}

curl https://<org-uuid>.production.tratta.io/api/v1/payment-plans/{payment-plan-uuid} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Returns

{
  "success": "boolean"
}

← Charges Payment Methods →