Tratta Docs

# Customer Sessions

Creating customer session allows customers to log in to the Portal. You can use this endpoint to generate url that customer will be redirected to. By default customer session expires after 24 hours from the most recent time used.

# Create Customer Session

POST https://<org-uuid>.production.tratta.io/api/v1/customer-sessions

curl https://<org-uuid>.production.tratta.io/api/v1/customer-sessions \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d customer_id="customer-uuid" \
 -d expiration_return_url="https://example.com/return-url"

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

debt_account_id optional|string

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

URL pointing to Debt Account detail can be generated with optional debt_account_id instead of customer_id.

debt_account_dispute_id optional|string

Used to redirect customer to specific dispute detail page. The id (uuid) of the dispute generated in Tratta can be found in Console.

valid_until optional|integer

Indicates how long session link should be active for in hours. Session will expire after the number of hours specified.

By default customer session expires after 24 hours from the most recent time used. Maximum time limit for session link is 90 days (2160 hours).

return_url optional|url

When customer successfully pays, they will be redirected to return_url.

expiration_return_url optional|url

If session expires, customer will be redirected from Portal to expiration_return_url specified here.

destination optional|string

Supported values:

  • accounts_list : when customer_id is present in the request body.
  • accounts_list, account_checkout, account_detail, account_documents : when debt_account_id is present in the request body.
  • account_disputes_detail: when debt_account_dispute_id is present in the request body.

tags optional|array

You can provide tags which will be appended as query parameters to customer session url. Each tag consists of name and value.

When you add parameters to a URL, you should always use utm_medium and utm_campaign. Tratta will automatically add the utm_source based on the user ID.

{
  "tags": [{
    "name": "utm_medium",
    "value": "sms"
  }, {
    "name": "utm_campaign",
    "value": "tax_season"
  },...]
}

Supported values for name:

  • utm_medium
  • utm_campaign
  • utm_content
  • utm_id

short_link optional|boolean

If passed along true, we'll shorten the url and append it as short_url to response. This shortened version of full url redirects to the original customer session url when accessed.

{
  "short_url": "https://bllpy.link/p/<hash>"
}

verification optional|boolean

Enables verification step when Portal accessed through generated Customer Session.

# Returns

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

{
  "id": "string",
  "portal_url": "url",
  "return_url": "url",
  "short_url": "url",
  "valid_till": "ISO8601"
}

# Create Customer Sessions in Bulk

Allows you to create up to 100 Customer Sessions in a single request synchronously. This endpoint is throttled to 30 requests per minute.

POST https://<org-uuid>.production.tratta.io/api/v1/bulk/customer-sessions

When creating Customer Sessions in bulk, you can use the same parameters as when creating the single Customer Session.

[
  {
    "customer_id": "<customer_id_1>",
    "short_link": true,
  },
  {
    "customer_id": "<customer_id_1>"
  }
]

# Returns

A json with data property that contains created array with customer session objects. We also include the original customer_id or debt_account_id or debt_account_dispute_id you have provided in the bulk payload, which should help you pair the results from the bulk endpoint to your request structure.

[{
  "id": "string",
  "customer_id": "string",
  "debt_account_id": "string",
  "debt_account_dispute_id": "string",
  "portal_url": "url",
  "return_url": "url",
  "short_url": "url",
  "valid_till": "ISO8601"
}, {
  "id": "string",
  "customer_id": "string",
  "debt_account_id": "string",
  "debt_account_dispute_id": "string",
  "portal_url": "url",
  "return_url": "url",
  "short_url": "url",
  "valid_till": "ISO8601"
},...]

# Integrating Url Redirects into your App

<form method="POST" action="/create-customer-session">
  <button type="submit">Pay</button>
</form>
  1. /create-customer-session on your app's backend calls Create Customer Session
  2. Your backend redirects customer's request to portal_url from response.

← Bulk →