> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Installments Plan
Yuno allows you to create installment plans to offer to your customers. These plans can be used based on factors such as the amount to pay, currency, and card used, as described below:
* **Filtered by Amount Range (mandatory):** The system checks if the installment plan is suitable for the specific amount of your transaction. Only plans that can handle that amount are considered.
* **Card BIN:** The system verifies if the BIN of your card matches those allowed for certain installment plans. If there's a match, that plan is considered.
* **Specific Currency:** Only plans that work with the currency you are using are considered.
* **Plan Availability:** The system checks if the installment plan is active. Only plans that have not expired and are available are considered.
**Defining the Plan ID**
The `plan_id` is only necessary when applying a fixed installment plan that doesn't change during the purchase. If the `installment.plan_id` is not provided, the SDK will automatically search through all available installment plans associated with that account and select the one it considers most suitable. You should include the `plan_id` to ensure that a specific plan is applied.
**Merchants Installments**
This endpoint is only required for [Merchant installments integration](/docs/installments). For Provider defined installments, we use the installment plan defined by your payment provider.
For merchant-created installments, you also have the possibility of specifying the plan for every checkout session by using the `plan_id` while [creating the session](/reference/create-checkout-session). If you do not send it, we will use the installment plan that matches the conditions set for the checkout session.
## OpenAPI
````yaml openapi/installments/create-installments-plan.json POST /installments-plans
openapi: 3.1.0
info:
title: installments
version: 1.0.2
servers:
- url: https://api-sandbox.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/installments-plans:
post:
summary: Create Installments Plan
operationId: create-installments-plan
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- account_id
- merchant_reference
- installments_plan
properties:
name:
type: string
description: The installment plan name (MAX 255; MIN 3)
account_id:
type: array
description: >-
The unique identifier(s) of the account(s) that will have
the installment plan (UUID; 36 chars).
default: '{{account_id}}'
items:
type: string
merchant_reference:
type: string
description: Identification of the installment plan (MAX 255; MIN 3)
installments_plan:
type: array
description: Definition of installments available for each scenario
items:
properties:
installment:
type: integer
description: The number of monthly installments shoppers can choose
format: int32
rate:
type: number
description: >-
The rate applied to the final amount of the
transaction by the payment provider after using
installments. The value should be entered as a
multiplier, not a percentage. For example, to apply a
20% rate, enter `1.20` instead of `20`.
format: float
financial_costs:
type: array
description: >-
Optional financial costs details for this installment
option.
items:
type: object
properties:
type:
type: string
description: >-
The financial cost type identifier (MIN 3; MAX
255).
Example: `CFT`, `TEA`, `CET`, `CAT`
rate:
type: number
description: >-
The financial cost rate as a decimal number
(e.g., 45.25 for 45.25%).
minimum: 0
maximum: 100000
format: float
default: ''
required:
- type
- rate
type:
type: string
description: >-
Installment’s type. Only available for Ecuador and
Mexico. Merchant refers to payments deferred with
interest, and Issuer refer to payments deferred
without interest
enum:
- MERCHANT_INSTALLMENTS
- ISSUER_INSTALLMENTS
required:
- installment
type: object
country_code:
type: string
description: The issuer's country (ISO 3166-1 MAX 2; MIN 2)
brand:
type: array
description: Card’s [brand](brands) information (MAX 255; MIN 3).
items:
type: string
issuer:
type: string
description: Card issuer (MAX 255; MIN 3)
iin:
type: array
description: >-
The issuer identification number (IIN) refers to the first
few digits of a payment card number issued by a financial
institution (MAX 8; MIN 6)
items:
type: string
first_installment_deferral:
type: integer
description: >-
The amount of months to wait to debit the first installment
(MAX: 3).
format: int32
amount:
type: object
description: >-
The amounts that the installment plan will be available for.
If null, available for any amount.
required:
- currency
properties:
currency:
type: string
description: >-
The currency used to make the payment (ISO 4217 MAX 3;
MIN 3)
min_value:
type: number
description: >-
The minimum amount the installment plan will be
available to use (multiple of 0.0001).
format: float
max_value:
type: number
description: >-
The maximum amount the installment plan will be
available to use (multiple of 0.0001).
format: float
availability:
type: object
description: >-
The dates that the installment plan will be available for.
If null then it does not have a finish date
properties:
start_at:
type: string
description: >-
The start date that the installment plan will be
available to use (UTC format)
format: date-time
finish_at:
type: string
description: >-
The end date until the installment plan will be
available to use (UTC format)
format: date-time
payment_method_type:
type: string
description: >-
Allows specifying the payment method type when creating an
installment plan.
enum:
- CARD
- NU_PAY_ENROLLMENT
examples:
Request Example:
value:
name: plan_007
account_id:
- '{{account-code}}'
merchant_reference: Test
installments_plan:
- installment: 1
rate: 1
- installment: 3
rate: 1
financial_costs:
- type: CFT
rate: 45.25
- type: TEA
rate: 38.5
- installment: 6
rate: 1
- installment: 9
rate: 1
- installment: 12
rate: 1
country_code: CO
amount:
currency: COP
min_value: 0
max_value: 100000000
availability:
start_at: '2023-09-12T00:00:00Z'
finish_at: '2030-09-20T00:00:00Z'
payment_method_type: NU_PAY_ENROLLMENT
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
id: 4d573425-33f9-4c46-b009-2c7e749b0ec7
name: plan_007
account_id:
- f7c5fe77-721b-49c2-84d3-957748df3c2c
merchant_reference: Test
installments_plan:
- installment: 1
rate: 1
provider_id: ''
- installment: 3
rate: 1
provider_id: ''
financial_costs:
- type: CFT
rate: 45.25
formatted_value: 45,25%
- type: TEA
rate: 38.5
formatted_value: 38,50%
- installment: 6
rate: 1
provider_id: ''
- installment: 9
rate: 1
provider_id: ''
- installment: 12
rate: 1
provider_id: ''
type: ''
source: ''
provider_id: ''
scheme: ''
brand:
- VISA
issuer: ''
issuer_id: ''
iin: null
country_code: US
first_installment_deferral: 0
amount:
Currency: USD
min_value: 0
max_value: 100000000
availability:
start_at: '2023-09-12T00:00:00Z'
finish_at: '2030-09-20T00:00:00Z'
payment_method_type: NU_PAY_ENROLLMENT
created_at: '2023-10-11T17:52:31.886178246Z'
updated_at: '2023-10-11T17:52:31.886178246Z'
schema:
type: object
properties:
id:
type: string
example: 4d573425-33f9-4c46-b009-2c7e749b0ec7
name:
type: string
example: plan_007
account_id:
type: array
items:
type: string
example: f7c5fe77-721b-49c2-84d3-957748df3c2c
merchant_reference:
type: string
example: Test
installments_plan:
type: array
items:
type: object
properties:
installment:
type: integer
example: 1
default: 0
rate:
type: integer
example: 1
default: 0
provider_id:
type: string
example: ''
financial_costs:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CFT
- TEA
- CET
- CAT
rate:
type: number
format: float
formatted_value:
type: string
type:
type: string
example: ''
source:
type: string
example: ''
provider_id:
type: string
example: ''
scheme:
type: string
example: ''
brand:
type: array
items:
type: string
example: VISA
issuer:
type: string
example: ''
issuer_id:
type: string
example: ''
iin: {}
country_code:
type: string
example: US
first_installment_deferral:
type: integer
example: 0
default: 0
amount:
type: object
properties:
Currency:
type: string
example: USD
min_value:
type: integer
example: 0
default: 0
max_value:
type: integer
example: 100000000
default: 0
availability:
type: object
properties:
start_at:
type: string
example: '2023-09-12T00:00:00Z'
finish_at:
type: string
example: '2030-09-20T00:00:00Z'
created_at:
type: string
example: '2023-10-11T17:52:31.886178246Z'
updated_at:
type: string
example: '2023-10-11T17:52:31.886178246Z'
payment_method_type:
type: string
example: NU_PAY_ENROLLMENT
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
code: INVALID_REQUEST
messages:
- Invalid request
schema:
type: object
properties: {}
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````