Skip Navigation
Log In Sign Up

Loan Object

·

The Loan object represents a financial loan created through the Tupel API. It includes details about the borrower entity, payment method, recipient, financial terms, and current status.

Attributes

  • uid string
    Unique identifier for the loan.

  • entity object
    The Entity object representing the borrower or customer. Contains company information such as name, jurisdiction, and registration details.

  • status string
    Current status of the loan. Possible values: PENDING, OPEN, CLOSED, OVERDUE.

  • currency string
    Three-letter ISO currency code for the loan (e.g., USD, EUR, GBP, or other accepted currency codes).

  • principal decimal
    The initial loan amount.

  • paid decimal
    The amount that has been paid back so far. Defaults to 0.00.

  • balance decimal
    The remaining amount to be paid on the loan.

  • rate decimal
    The daily interest rate for the loan.

  • fee decimal
    The month-to-date accrual of daily interest. Resets to zero at the start of every month. Defaults to 0.00.

  • due_at timestamp
    The date and time when the loan repayment is due.

  • pay_at timestamp
    The date and time when the loan should be paid out to the recipient.

  • reference nullable string
    Optional reference information for the loan.

  • recipient object
    The Recipient object representing where the loan funds will be sent.

  • payment_method object
    The Payment Method object representing how repayments will be made.

  • created_at timestamp
    Time at which the loan was created.

  • updated_at timestamp
    Time at which the loan was last updated.

More Attributes

  • payments array of objects
    List of Payment objects associated with this loan.

  • invoices array of objects
    List of Invoice objects associated with this loan.

  • attachments array of objects
    List of Attachment objects with supporting documentation for this loan.

  • installments array of timestamps
    Due dates for loan repayments.

Creating a Loan

To create a new loan, use a POST request to /api/loans/ with the following parameters:

Required Parameters

  • entity string
    The UID of the entity (borrower) for the loan.

  • currency string
    Three-letter ISO currency code (USD, EUR, GBP, or other accepted currency codes).

  • principal decimal
    The amount to be loaned.

  • pay_at timestamp
    When the loan should be paid out.

  • due_at timestamp
    When the loan should be paid back.

  • recipient string
    The UID of the recipient where funds will be sent.

  • payment_method string
    The UID of the payment method for repayments.

Optional Parameters

  • installments integer
    Number of installments for repayment. Defaults to 1.

  • reference string
    Additional reference information. Defaults to empty string.

Example Loan Object

{
  "uid": "8fJ3k2hG",
  "entity": {
    "uid": "7Ba9c2E4f",
    "name": "Acme Corporation",
    "jurisdiction": "US",
    "incorporated_at": "2018-05-12",
    "status": "ACTIVE",
    "type": "LTD",
    "registration_number": "US12345678",
    "tax_number": "987654321",
    "email": "finance@acmecorp.com",
    "created_at": "2023-01-15T14:32:17Z",
    "updated_at": "2023-01-15T14:32:17Z"
  },
  "status": "OPEN",
  "currency": "USD",
  "principal": "50000.00",
  "paid": "12500.00",
  "balance": "37500.00",
  "rate": "0.05",
  "fee": "500.00",
  "due_at": "2023-12-15T23:59:59Z",
  "pay_at": "2023-03-01T12:00:00Z",
  "reference": "Q1-2023-Equipment",
  "recipient": {
    "uid": "Ab3D9f2c",
    "entity": {
      "uid": "7Ba9c2E4f",
      "name": "Acme Corporation",
      "jurisdiction": "US",
      "incorporated_at": "2018-05-12",
      "status": "ACTIVE",
      "type": "LTD",
      "registration_number": "US12345678",
      "tax_number": "987654321",
      "email": "finance@acmecorp.com",
      "created_at": "2023-01-15T14:32:17Z",
      "updated_at": "2023-01-15T14:32:17Z"
    },
    "type": "CHECKING",
    "recipient_type": "BUSINESS",
    "owner": "Acme Corporation",
    "currency": "USD",
    "bank_code": "021000021",
    "branch_code": null,
    "account_number": "9876543210",
    "is_owned": true,
    "email": "finance@acmecorp.com",
    "created_at": "2023-01-20T09:15:23Z",
    "updated_at": "2023-01-20T09:15:23Z"
  },
  "payment_method": {
    "uid": "2qP3oN4m",
    "entity": {
      "uid": "7Ba9c2E4f",
      "name": "Acme Corporation",
      "jurisdiction": "US",
      "incorporated_at": "2018-05-12",
      "status": "ACTIVE",
      "type": "LTD",
      "registration_number": "US12345678",
      "tax_number": "987654321",
      "email": "finance@acmecorp.com",
      "created_at": "2023-01-15T14:32:17Z",
      "updated_at": "2023-01-15T14:32:17Z"
    },
    "type": "ACH",
    "currency": "USD",
    "last4": "3210",
    "created_at": "2023-01-22T11:45:36Z",
    "updated_at": "2023-01-22T11:45:36Z"
  },
  "payments": [
    {
      "uid": "9sK8jH7g",
      "type": "DEBIT",
      "method": "ACH",
      "status": "SETTLED",
      "reason": "PRINCIPAL",
      "provider": "WISE",
      "currency": "USD",
      "amount": "12500.00",
      "normalized_currency": "USD",
      "normalized_amount": "12500.00",
      "paid_at": "2023-06-15T14:32:17Z",
      "delivered_at": "2023-06-16T09:15:23Z",
      "created_at": "2023-06-15T14:32:17Z",
      "updated_at": "2023-06-16T09:15:23Z",
      "attachments": [],
      "fx_rate": {
        "source_currency": "USD",
        "target_currency": "USD",
        "bid": "1.0",
        "ask": "1.0",
        "mid": "1.0",
        "timestamp": "2023-06-15T14:30:00Z"
      }
    }
  ],
  "invoices": [],
  "attachments": [
    {
      "uid": "1aB2cD3e",
      "type": "LOAN_AGREEMENT",
      "file": "https://tupel.com/api/files/loan_agreement_8fJ3k2hG.pdf",
      "created_at": "2023-03-01T10:25:36Z",
      "updated_at": "2023-03-01T10:25:36Z"
    }
  ],
  "installments": [
    "2023-05-15T23:59:59Z",
    "2023-08-15T23:59:59Z",
    "2023-10-15T23:59:59Z",
    "2023-12-15T23:59:59Z"
  ],
  "created_at": "2023-03-01T10:25:36Z",
  "updated_at": "2023-06-16T09:15:23Z"
}