v2

Promissory Notes
Promissory Note Endpoints

>>>

GET /promissory_notes?page=&per=
List of Promissory Notes

Params

Param name Description
page
optional

Page index

Validations:

  • Must be a Integer
per
optional

Items per page

Validations:

  • Must be a Integer

Examples

{
  'data': [
    {
  'id': 'promissory-note-uuid',
  'initial_amount': '100000.00',
  'balance': '100000.00',
  'current_balance': '100000.00',
  'parent_id': 'parent-uuid',
  'folio': 'TEST-FOLIO',
  'currency': { 'name': 'MXN', 'value': 'mxn' },
  'interest_rate': '10.00',
  'start_date': '2026-01-01',
  'end_date': '2026-12-31',
  'interest_rate_unformatted': '10.0',
  'monthly_periodicity': 1,
  'tax_percentage': '1.00',
  'canceled_date': null,
  'current_tax_percentage': '1.00',
  'cut_day': 31,
  'status': 'Inactive',
  'society': {
    'id': 'society-uuid',
    'name': 'Test Society',
    'business_name': 'Test Society',
    'default': true,
    'is_financial_entity': true
  },
  'society_id': 'society-uuid',
  'organization_id': 'org-uuid',
  'investor': {
    'id': 'investor-uuid',
    'name': 'Test',
    'full_name': 'Test User',
    'company': false,
    'company_name': null
  },
  'investor_id': 'investor-uuid',
  'promoter_id': 'promoter-uuid',
  'promoter_commission': '2.00',
  'promoter_payment_method': 'electronic_funds_transfer',
  'interest_rate_ceiling': '15.00',
  'interest_rate_floor': '10.00',
  'includes_external_rate': false,
  'variable_rate_days': null,
  'variable_rate_date': null,
  'external_rate_label': null,
  'external_rate_label_translated': null,
  'additional_interest_rate': '0.0',
  'variable_rate_days_translated': '',
  'rate_type': 'Fixed',
  'type_of': { 'name': 'Simple', 'value': 'simple' },
  'created_at': '2026-01-01 - 10:00',
  'payment_on_expiration?': false,
  'pending_movements': false,
  'updated_at': '2026-01-01 - 10:00'
}
  ],
  'meta': {
    'count': 1
  }
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

GET /promissory_note/:id
Specific promissory note

Params

Param name Description
id
required

Requested promissory note ID

Validations:

  • Must be a String

Examples

{
  'data': {
  'id': 'promissory-note-uuid',
  'initial_amount': '100000.00',
  'balance': '100000.00',
  'current_balance': '100000.00',
  'parent_id': 'parent-uuid',
  'folio': 'TEST-FOLIO',
  'currency': { 'name': 'MXN', 'value': 'mxn' },
  'interest_rate': '10.00',
  'start_date': '2026-01-01',
  'end_date': '2026-12-31',
  'interest_rate_unformatted': '10.0',
  'monthly_periodicity': 1,
  'tax_percentage': '1.00',
  'canceled_date': null,
  'current_tax_percentage': '1.00',
  'cut_day': 31,
  'status': 'Inactive',
  'society': {
    'id': 'society-uuid',
    'name': 'Test Society',
    'business_name': 'Test Society',
    'default': true,
    'is_financial_entity': true
  },
  'society_id': 'society-uuid',
  'organization_id': 'org-uuid',
  'investor': {
    'id': 'investor-uuid',
    'name': 'Test',
    'full_name': 'Test User',
    'company': false,
    'company_name': null
  },
  'investor_id': 'investor-uuid',
  'promoter_id': 'promoter-uuid',
  'promoter_commission': '2.00',
  'promoter_payment_method': 'electronic_funds_transfer',
  'interest_rate_ceiling': '15.00',
  'interest_rate_floor': '10.00',
  'includes_external_rate': false,
  'variable_rate_days': null,
  'variable_rate_date': null,
  'external_rate_label': null,
  'external_rate_label_translated': null,
  'additional_interest_rate': '0.0',
  'variable_rate_days_translated': '',
  'rate_type': 'Fixed',
  'type_of': { 'name': 'Simple', 'value': 'simple' },
  'created_at': '2026-01-01 - 10:00',
  'payment_on_expiration?': false,
  'pending_movements': false,
  'updated_at': '2026-01-01 - 10:00'
}
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

GET /promissory_notes/:id/fiscal_breakdowns
Fiscal breakdowns of a promissory note

Params

Param name Description
id
required

Promissory note ID

Validations:

  • Must be a String

Examples

# Response (200 OK):
{
  'data': [
    {
      'id': 'fiscal-breakdown-uuid',
      'start_date': '2026-01-01',
      'end_date': '2026-01-31',
      'balance': '100000.00',
      'gross': '849.32',
      'accumulated': '849.32',
      'number_of_days': 31,
      'status': 'active',
      'fiscalable_type': 'PromissoryNote',
      'fiscalable_id': 'promissory-note-uuid',
      'natural_end_date': '2026-01-31',
      'natural_number_of_days': 31
    }
  ],
  'meta': {
    'count': 1
  }
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

POST /promissory_notes/:id/recalculate
Trigger recalculation of a promissory note

Params

Param name Description
id
required

Promissory note ID

Validations:

  • Must be a String

Examples

# No request body required.
# Response (204 No Content) on success.

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

POST /promissory_notes/calculate_preview_interests
Preview interest schedule for a promissory note

Params

Param name Description
promissory_note
required

Promissory note attributes for preview

Validations:

  • Must be a Hash
promissory_note[initial_amount]
required

Initial investment amount

Validations:

  • Must be a String
promissory_note[start_date]
required

Start date (YYYY-MM-DD)

Validations:

  • Must be a String
promissory_note[end_date]
required

End date (YYYY-MM-DD)

Validations:

  • Must be a String
promissory_note[interest_rate]
required

Annual interest rate

Validations:

  • Must be a String
promissory_note[currency]
required

Currency

Validations:

  • Must be one of: mxn, usd.
promissory_note[type_of]
optional

Type of promissory note (e.g. simple, compound)

Validations:

  • Must be a String
promissory_note[monthly_periodicity]
optional

Payment periodicity in months

Validations:

  • Must be a Integer
promissory_note[tax_percentage]
optional

Withholding tax percentage

Validations:

  • Must be a String
promissory_note[cut_day]
optional

Day of month for interest cuts

Validations:

  • Must be a Integer
promissory_note[includes_external_rate]
optional

Whether rate includes an external reference

Validations:

  • Must be one of: true, false, 1, 0.
promissory_note[interest_rate_floor]
optional

Minimum interest rate floor

Validations:

  • Must be a String
promissory_note[interest_rate_ceiling]
optional

Maximum interest rate ceiling

Validations:

  • Must be a String
promissory_note[society_id]
optional

Society UUID

Validations:

  • Must be a String
promissory_note[investor_id]
optional

Investor UUID (or omit and pass calculator: true for preview without a real investor)

Validations:

  • Must be a String
promissory_note[promoter_id]
optional

Promoter UUID

Validations:

  • Must be a String
promissory_note[calculator]
optional

Set to true to run preview without requiring a real investor/promoter

Validations:

  • Must be one of: true, false, 1, 0.

Examples

# Request body:
{
  'calculator': true,
  'promissory_note': {
    'initial_amount': '500000.00',
    'start_date': '2026-05-07',
    'end_date': '2027-05-07',
    'interest_rate': '10.5',
    'currency': 'mxn',
    'type_of': 'simple',
    'monthly_periodicity': 1,
    'tax_percentage': '1.04',
    'cut_day': 31,
    'society_id': 'society-uuid',
    'configuration': {
      'day_count_algorithm': '30 days',
      'fiscal_year_days': 360,
      'end_date_excluded': true,
      'event_date_included': true,
      'start_date_excluded': true
    }
  }
}

# Response (200 OK):
{
  'data': {
    'initial_amount': '500000.00',
    'currency': { 'name': 'MXN', 'value': 'mxn' },
    'interest_rate': '10.50',
    'start_date': '2026-01-01',
    'end_date': '2027-01-01',
    'monthly_periodicity': 1,
    'tax_percentage': '1.04',
    'type_of': { 'name': 'Simple', 'value': 'simple' },
    'interest_breakdown': [
      {
        'start_date': '2026-01-01',
        'end_date': '2026-01-31',
        'number_of_days': 31,
        'rate': '10.50',
        'gross': '4458.90',
        'tax': '46.37',
        'net': '4412.53'
      }
    ]
  }
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error