Skip Navigation
Log In Sign Up

Repay a Loan

·

Process a repayment for an existing loan by sending a POST request to the loan repayment endpoint.

Request

POST https://tupel.com/api/loans/{uid}/repay/

Authentication

This endpoint requires basic authentication with your Organization ID and API Key.

Path Parameters

  • uid string Required
    The unique identifier of the loan to repay.

Request Body Parameters

  • currency string Required
    Three-letter ISO currency code for the repayment. Supported values: USD, EUR, GBP, or other accepted currency codes. Must match the loan's currency.

  • amount decimal Required
    The amount to repay. Must be a positive number.

Repayment Process

When a repayment is initiated:

  1. A new payment with status PENDING is created
  2. Funds are collected from the payment method associated with the loan
  3. Once the collection is successful, the payment status is updated to SETTLED
  4. The loan's paid amount is increased and the balance is decreased
  5. If the loan is fully repaid, its status is updated to CLOSED

Partial Repayments

The API supports partial repayments:

  • The repayment amount can be less than the total outstanding balance
  • Multiple repayments can be made against the same loan
  • For loans with installments, partial repayments reduce the outstanding balance and as such are applied to the all due installments equally

Currency Considerations

  • The repayment currency must match the loan's currency
  • If you need to make a repayment in a different currency, you must handle the currency conversion before calling this endpoint

Payment Methods

Repayments are collected using the payment method specified when the loan was created. The payment method cannot be changed for an individual repayment.

Notes

  • Given payments are run asynchronously, the loan response may not have the new payment in the payments array.
  • The payment initially has a status of PENDING until the funds are collected successfully.
  • For visibility into the payment status, you should periodically check the loan details using the Retrieve a Loan endpoint.
  • If a payment fails (e.g., due to insufficient funds), the payment status will be updated to FAILED and the loan balance will remain unchanged.
  • Interest calculations are handled automatically based on the loan's rate and the time since disbursement.
  • For loans that are not in an OPEN status, repayment requests will result in an error.

Example Request

curl -X POST https://tupel.com/api/loans/loan_9hK7jL6mN5pQ4rS/repay/ \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY> \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": "12500.00"
  }'

Response

A successful request returns a 200 OK status code and the updated Loan in the response body. Given payments are run asynchronously, the loan returned may (or may not) have the new payment in the payments array.

Error Responses

Code Description
401 Unauthorized - Authentication failed. Check your Organization ID and API Key.
403 Forbidden - Insufficient permissions to repay this loan.
404 Not Found - The specified loan could not be found.
422 Unprocessable Entity - Validation error in the request parameters.

Example Error Response

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "currency"],
      "msg": "Currency must match the loan currency (USD)."
    }
  ]
}