From c7759bef751f9ed2fb3905f0d794c56a7eb2a486 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Wed, 5 Aug 2026 11:08:18 -0400 Subject: [PATCH 1/3] feat(msi): add POST /monthly_installments/validate to the spec The endpoint exists in payments-api (config/routes.rb:736 -> MonthlyInstallmentsController#validate) and the public dev center documents it as step 1 of the Direct API MSI flow, but it was absent from the spec, so no SDK exposes it. Request and response schemas are derived from BinValidatorService: request - bin (6 or 8 digits, 8 falls back to 6 on no match), amount in minor units response - available_installments[{months, amount}] and bin_info{country, scheme, issuer}, both always present (#retrieve_legacy / #retrieve_via_engine) available_installments is documented as legitimately empty for a card that does not qualify, since #retrieve_monthly_installments returns [] rather than raising when validate_card_rules? fails. _build/api.yaml is NOT regenerated: `make merge` needs a running Docker daemon, which was unavailable. Run `make merge` before merging. Co-Authored-By: Claude Opus 5 (1M context) --- api.yaml | 2 + .../monthly_installments_validate.yml | 6 +++ .../monthly_installments_validate.yml | 51 +++++++++++++++++++ .../monthly_installments_validate.yml | 18 +++++++ ...monthly_installments_validate_response.yml | 44 ++++++++++++++++ 5 files changed, 121 insertions(+) create mode 100644 requestBodies/monthly_installments/monthly_installments_validate.yml create mode 100644 resources/monthly_installments/monthly_installments_validate.yml create mode 100644 schemas/monthly_installments/monthly_installments_validate.yml create mode 100644 schemas/monthly_installments/monthly_installments_validate_response.yml diff --git a/api.yaml b/api.yaml index f8340e4..789f090 100644 --- a/api.yaml +++ b/api.yaml @@ -68,6 +68,8 @@ paths: $ref: "./resources/logs/log.yml" /logs/{id}: $ref: "./resources/logs/log_by_id.yml" + /monthly_installments/validate: + $ref: "./resources/monthly_installments/monthly_installments_validate.yml" /orders: $ref: "./resources/orders/order.yml" /orders/{id}: diff --git a/requestBodies/monthly_installments/monthly_installments_validate.yml b/requestBodies/monthly_installments/monthly_installments_validate.yml new file mode 100644 index 0000000..d5133c7 --- /dev/null +++ b/requestBodies/monthly_installments/monthly_installments_validate.yml @@ -0,0 +1,6 @@ +description: requested field for monthly installments validate +content: + application/json: + schema: + $ref: '../../schemas/monthly_installments/monthly_installments_validate.yml' +required: true diff --git a/resources/monthly_installments/monthly_installments_validate.yml b/resources/monthly_installments/monthly_installments_validate.yml new file mode 100644 index 0000000..56fd8bb --- /dev/null +++ b/resources/monthly_installments/monthly_installments_validate.yml @@ -0,0 +1,51 @@ +post: + tags: + - Monthly Installments + operationId: validateMonthlyInstallments + summary: Validate Monthly Installments + description: | + Returns the interest-free monthly installment plans available for a card BIN and an amount, so a checkout can offer only the plans a later charge will accept. Requires monthly installments to be enabled on the company. + responses: + 200: + description: successful operation + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: '../../schemas/monthly_installments/monthly_installments_validate_response.yml' + headers: + Date: + description: The date and time that the response was sent + schema: + type: string + example: "Fri, 03 Feb 2023 16:57:48 GMT" + Content-Type: + description: The format of the response body + schema: + type: string + example: "application/json; charset=utf-8" + Content-Length: + description: The length of the response body in bytes + schema: + type: string + example: "245" + Connection: + description: The type of connection used to transfer the response + schema: + type: string + example: "keep-alive" + Conekta-Media-Type: + schema: + type: string + example: conekta-v2.3.0; format=application/json + 401: + $ref: '../errors/401.yml' + 422: + $ref: '../errors/422.yml' + 500: + $ref: '../errors/500.yml' + security: + - bearerAuth: [] + requestBody: + $ref: '../../requestBodies/monthly_installments/monthly_installments_validate.yml' + parameters: + - $ref: '../../parameters/commons/headers/accept_language.yml' diff --git a/schemas/monthly_installments/monthly_installments_validate.yml b/schemas/monthly_installments/monthly_installments_validate.yml new file mode 100644 index 0000000..71c7b8e --- /dev/null +++ b/schemas/monthly_installments/monthly_installments_validate.yml @@ -0,0 +1,18 @@ +title: monthly installments validate request +description: BIN and amount to evaluate for interest-free monthly installments +type: object +required: + - bin + - amount +properties: + bin: + type: string + description: "First 6 or 8 digits of the card number (Bank Identification Number). An 8 digit BIN that yields no match is retried with its first 6 digits." + example: "411111" + minLength: 6 + maxLength: 8 + pattern: '^[0-9]{6}(?:[0-9]{2})?$' + amount: + type: integer + description: "Amount to charge in the smallest currency unit (cents for MXN). Used to compute the monthly fee of each available plan." + example: 350000 diff --git a/schemas/monthly_installments/monthly_installments_validate_response.yml b/schemas/monthly_installments/monthly_installments_validate_response.yml new file mode 100644 index 0000000..2e15515 --- /dev/null +++ b/schemas/monthly_installments/monthly_installments_validate_response.yml @@ -0,0 +1,44 @@ +title: monthly_installments_validate_response +description: monthly installments validate response +type: object +required: + - available_installments + - bin_info +properties: + available_installments: + title: monthly_installments_validate_response_available_installments + type: array + description: "Interest-free monthly installment plans available for this card and amount. Empty when the card does not qualify for monthly installments, for example a debit card or a credit card not issued in Mexico. An empty array is not an error." + items: + type: object + required: + - months + - amount + properties: + months: + type: integer + description: "Number of monthly installments of the plan. One of 3, 6, 9, 12, 18 or 24." + example: 3 + amount: + type: integer + description: "Amount of each monthly installment in the smallest currency unit, rounded up." + example: 116667 + bin_info: + type: object + required: + - country + - scheme + - issuer + properties: + country: + type: string + description: "Country that issued the card. Monthly installments only apply to mx, with the exception of American Express." + example: "mx" + scheme: + type: string + description: "Card scheme. Monthly installments only apply to credit." + example: "credit" + issuer: + type: string + description: "Bank that issued the card." + example: "banamex" From fcc5c39ae80809401e6e5fb3c7bdfac64d5309fd Mon Sep 17 00:00:00 2001 From: franklin Date: Thu, 3 Sep 2026 10:49:20 -0500 Subject: [PATCH 2/3] chore(build): regenerate _build/api.yaml with monthly installments validate endpoint Integrates the `/monthly_installments/validate` endpoint into the compiled OpenAPI specification, completing the work introduced in the previous `feat(msi)` commit. --- _build/api.yaml | 196 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) diff --git a/_build/api.yaml b/_build/api.yaml index 0f992cb..de7a7d8 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -5517,6 +5517,129 @@ paths: summary: Get Log tags: - Logs + /monthly_installments/validate: + post: + description: | + Returns the interest-free monthly installment plans available for a card BIN and an amount, so a checkout can offer only the plans a later charge will accept. Requires monthly installments to be enabled on the company. + operationId: validateMonthlyInstallments + parameters: + - description: Use for knowing which language to use + examples: + es: + summary: for spanish request/response + value: es + en: + summary: for english request/response + value: en + explode: false + in: header + name: Accept-Language + required: false + schema: + default: es + enum: + - es + - en + type: string + style: simple + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/monthly_installments_validate_request" + description: requested field for monthly installments validate + required: true + responses: + "200": + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: "#/components/schemas/monthly_installments_validate_response" + description: successful operation + headers: + Date: + description: The date and time that the response was sent + explode: false + schema: + example: "Fri, 03 Feb 2023 16:57:48 GMT" + type: string + style: simple + Content-Type: + description: The format of the response body + explode: false + schema: + example: application/json; charset=utf-8 + type: string + style: simple + Content-Length: + description: The length of the response body in bytes + explode: false + schema: + example: "245" + type: string + style: simple + Connection: + description: The type of connection used to transfer the response + explode: false + schema: + example: keep-alive + type: string + style: simple + Conekta-Media-Type: + explode: false + schema: + example: conekta-v2.3.0; format=application/json + type: string + style: simple + "401": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: Please include your access key in your request. + code: conekta.errors.authentication.missing_key + log_id: 507f1f77bcf86cd799439011 + object: error + type: authentication_error + schema: + $ref: "#/components/schemas/error" + description: authentication error + "422": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The token does not exist. + param: payment_method.token_id + code: conekta.errors.parameter_validation.payment_method.token_id.nonexistent_token + debug_message: The token does not exist. + log_id: 641b6d813cd9a50001515017 + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: parameter validation error + "500": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - debug_message: There was a runtime error and Conekta engineers have + been notified. + message: There was a runtime error and Conekta engineers have been + notified. + code: conekta.errors.api.system.general_failure + object: error + type: api_error + log_id: 641b6f2b3cd9a50001515098 + schema: + $ref: "#/components/schemas/error" + description: internal server error + security: + - bearerAuth: [] + summary: Validate Monthly Installments + tags: + - Monthly Installments /orders: get: description: Get order details in the form of a list @@ -19680,6 +19803,79 @@ components: - id - livemode title: log_response_for_request + monthly_installments_validate_request: + description: BIN and amount to evaluate for interest-free monthly installments + properties: + bin: + description: First 6 or 8 digits of the card number (Bank Identification + Number). An 8 digit BIN that yields no match is retried with its first + 6 digits. + example: "411111" + maxLength: 8 + minLength: 6 + pattern: "^[0-9]{6}(?:[0-9]{2})?$" + type: string + amount: + description: Amount to charge in the smallest currency unit (cents for MXN). + Used to compute the monthly fee of each available plan. + example: 350000 + type: integer + required: + - amount + - bin + title: monthly installments validate request + monthly_installments_validate_response_available_installments_inner: + properties: + months: + description: "Number of monthly installments of the plan. One of 3, 6, 9,\ + \ 12, 18 or 24." + example: 3 + type: integer + amount: + description: "Amount of each monthly installment in the smallest currency\ + \ unit, rounded up." + example: 116667 + type: integer + required: + - amount + - months + monthly_installments_validate_response_bin_info: + properties: + country: + description: "Country that issued the card. Monthly installments only apply\ + \ to mx, with the exception of American Express." + example: mx + type: string + scheme: + description: Card scheme. Monthly installments only apply to credit. + example: credit + type: string + issuer: + description: Bank that issued the card. + example: banamex + type: string + required: + - country + - issuer + - scheme + monthly_installments_validate_response: + description: monthly installments validate response + properties: + available_installments: + description: "Interest-free monthly installment plans available for this\ + \ card and amount. Empty when the card does not qualify for monthly installments,\ + \ for example a debit card or a credit card not issued in Mexico. An empty\ + \ array is not an error." + items: + $ref: "#/components/schemas/monthly_installments_validate_response_available_installments_inner" + title: monthly_installments_validate_response_available_installments + type: array + bin_info: + $ref: "#/components/schemas/monthly_installments_validate_response_bin_info" + required: + - available_installments + - bin_info + title: monthly_installments_validate_response order_channel_response: properties: segment: From 85da63914c1e2a744e093849f2442f74a9e13fb0 Mon Sep 17 00:00:00 2001 From: franklin Date: Thu, 3 Sep 2026 10:53:24 -0500 Subject: [PATCH 3/3] fix naming --- _build/api.yaml | 6 +++--- .../monthly_installments_validate_response.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index de7a7d8..d4d5bf8 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -19824,7 +19824,7 @@ components: - amount - bin title: monthly installments validate request - monthly_installments_validate_response_available_installments_inner: + monthly_installments_validate_response_available_installments: properties: months: description: "Number of monthly installments of the plan. One of 3, 6, 9,\ @@ -19839,6 +19839,7 @@ components: required: - amount - months + title: monthly_installments_validate_response_available_installments monthly_installments_validate_response_bin_info: properties: country: @@ -19867,8 +19868,7 @@ components: \ for example a debit card or a credit card not issued in Mexico. An empty\ \ array is not an error." items: - $ref: "#/components/schemas/monthly_installments_validate_response_available_installments_inner" - title: monthly_installments_validate_response_available_installments + $ref: "#/components/schemas/monthly_installments_validate_response_available_installments" type: array bin_info: $ref: "#/components/schemas/monthly_installments_validate_response_bin_info" diff --git a/schemas/monthly_installments/monthly_installments_validate_response.yml b/schemas/monthly_installments/monthly_installments_validate_response.yml index 2e15515..139ccc3 100644 --- a/schemas/monthly_installments/monthly_installments_validate_response.yml +++ b/schemas/monthly_installments/monthly_installments_validate_response.yml @@ -6,10 +6,10 @@ required: - bin_info properties: available_installments: - title: monthly_installments_validate_response_available_installments type: array description: "Interest-free monthly installment plans available for this card and amount. Empty when the card does not qualify for monthly installments, for example a debit card or a credit card not issued in Mexico. An empty array is not an error." items: + title: monthly_installments_validate_response_available_installments type: object required: - months