# Create a loan snapshot

Create a new loan snapshot for a customer. Each successful request triggers an automatic direct debit collection attempt on the same day or the next Mexico business day. The response returns the id of the newly created snapshot. When the collection attempt completes, Belvo sends a webhook notification with the outcome.

Endpoint: POST /loans
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Request fields (application/json):

  - `paymentMethodId` (string, required)
    The paymentMethod.id associated with this loan. The payment method must exist and belong to the merchant.

  - `merchantCustomerId` (string, required)
    Your unique identifier for the customer. Maximum 50 characters, alphanumeric only.

  - `daysOverdue` (integer, required)
    The number of days the loan is overdue. Must be 0 or greater.

  - `totalBalance` (number, required)
    The total outstanding balance. Must be positive and not exceed 9999999999.99.

  - `principalAmount` (number, required)
    The principal amount of the loan. Must be positive and not exceed 9999999999.99.

  - `defaultDate` (string, required)
    The date that the customer defaulted on this loan, in YYYY-MM-DD format.

  - `issueDate` (string, required)
    The date the loan was originally issued, in YYYY-MM-DD format.

  - `loanAmount` (number)
    The original loan amount. Must be greater than 0.

  - `interestAmount` (number)
    The accumulated interest amount. Must be 0 or greater.

  - `feesAmount` (number)
    Any fees associated with the loan. Must be 0 or greater.

  - `latePaymentInterestAmount` (number)
    Interest accrued due to late payment. Must be 0 or greater.

  - `openingCommissionAmount` (number)
    Opening commission charged for the loan. Must be 0 or greater.

  - `yearlyOrdinalInterestRate` (number)
    The yearly interest rate with up to 4 decimal places.

  - `customerSalary` (number)
    The customer's salary. Must be positive and not exceed 99999999.99.

  - `customerAddress` (string)
    The customer's address. Maximum 200 characters.

  - `creditStatus` (string)
    The credit status of the loan. Can be either:
  - past_due
    Payment is past the due date.
  - restructured
    The loan has been restructured.
  - canceled
    The loan has been canceled.
  - in_arrears
    The loan is in arrears.
    Enum: "past_due", "restructured", "canceled", "in_arrears"

  - `paidInstallments` (integer)
    The number of installments already paid. Must be 0 or greater.

  - `paidAmount` (number)
    The total amount already paid. Must be 0 or greater.

  - `lastPaymentDate` (string)
    The date of the last payment in YYYY-MM-DD format.

  - `lastPaymentAmount` (number)
    The amount of the last payment. Must be 0 or greater.

  - `mainPhoneNumber` (string)
    The customer's main phone number with country code prefix.

  - `reference` (string)
    Your reference for this loan. Maximum 50 characters.

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier of the newly created loan history record.
    Example: "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 400

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Bad Request"

  - `message` (any)
    A short description of the error, indicating what is wrong with the request.
> Note: We return either a string or an array of strings, depending on the validation error(s). 

The description can be (among others):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 401

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Unauthorized"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
In the case of a 401 Unauthorized error, the message is:

  - Unauthorized credentials
    Example: "Unauthorized credentials"

## Response 403 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 403

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Forbidden"

  - `message` (string)
    A short description of the error, indicating why the request is forbidden.
    Example: "Forbidden"

## Response 404 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 404

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Not Found"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
The description can be (among others):

  - Payout Target not found
  - Payment method not found
  - Customer not found
    Example: "Payout Target not found"

## Response 409 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 409

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Conflict"

  - `message` (string)
    A short description of the error, indicating the nature of the conflict.
The description can be (among others):

  - A loan snapshot with this merchantCustomerId and defaultDate already exists
    Example: "A loan snapshot with this merchantCustomerId and defaultDate already exists"