fix(orders): tighten shipping address, line, and item schema constraints

schemas/checkouts/checkout.yml

@@ -25,11 +25,11 @@ properties:
   exclude_card_networks:
     title: checkout_exclude_card_networks
     type: array
-    description: "List of card networks to exclude from the checkout. This field is only applicable for card payments."
+    description: "List of card networks to exclude from the checkout. This field is only applicable for card payments. Accepted values: 'visa_master_card' (a single token excluding both Visa and Mastercard) and 'amex'."
     items:
       type: string
-      enum: ["visa", "mastercard", "amex"]
-    example: ["visa", "amex"]
+      enum: ["visa_master_card", "amex"]
+    example: ["visa_master_card"]
   expires_at:
     type: integer
     example: 1680397724
@@ -51,12 +51,15 @@ properties:
     example: [3,6,12]
   three_ds_mode:
     type: [string, "null"]
-    description: "Indicates the 3DS2 mode for the order, either smart or strict. This property is only applicable when 3DS is enabled. When 3DS is disabled, this field should be null."
+    enum: ["strict", "not_strict", "smart", null]
+    description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. Null appears in responses when no mode is configured; to defer to the company-level 3DS configuration, omit the field on creation (an explicit null is rejected)."
     examples:
       - value: "smart"
-        summary: "Those transactions that Conekta considers to present a risk to commerce will go through an additional verification flow (through 3DS2), provided that the issuing bank is compatible with this technology.If the transaction is not considered risky, it will continue its normal course, without going through 3DS2 authentication."
+        summary: "Risk-based 3DS: transactions that Conekta considers risky go through the 3DS2 verification flow (provided the issuing bank supports it); low-risk transactions continue without 3DS2 authentication."
       - value: "strict"
-        summary: "All transactions will require 3DS2 authentication as a complementary measure for the security of charges, except those that are rejected by our Anti-Fraud. The issuing bank must be compatible with 3DS2 technology."
+        summary: "All transactions require 3DS2 authentication as a complementary security measure, except those rejected by our Anti-Fraud. The issuing bank must support 3DS2."
+      - value: "not_strict"
+        summary: "The 3DS2 flow is also always initiated, behaving like 'strict'. Acceptance of authentication attempts is governed by the company-level 3DS configuration, not by this mode."
   name:
     type: string
     description: Reason for charge

schemas/checkouts/checkout_request.yml

@@ -20,11 +20,11 @@ properties:
   exclude_card_networks:
     title: checkout_request_exclude_card_networks
     type: array
-    description: "List of card networks to exclude from the checkout. This field is only applicable for card payments."
+    description: "List of card networks to exclude from the checkout. This field is only applicable for card payments. Accepted values: 'visa_master_card' (a single token excluding both Visa and Mastercard) and 'amex'."
     items:
       type: string
-      enum: ["visa", "mastercard", "amex"]
-    example: ["visa", "amex"]
+      enum: ["visa_master_card", "amex"]
+    example: ["visa_master_card"]
   plan_ids:
     type: array
     description: "List of plan IDs that will be available for subscription. This field is required for subscription payments."

schemas/customers/customer_address.yml

@@ -23,10 +23,5 @@ properties:
     type: string
     example: MX
     description: "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)"
-  residential:
-    type: boolean
-    example: true
-    default: false
   external_number:
     type: string
-

schemas/customers/customer_shipping_contacts.yml

@@ -13,36 +13,19 @@ properties:
     type: string
     example:   "Marvin Fuller"
     description: "Name of the person who will receive the order"
-  between_streets: 
+  between_streets:
     type: string
+    maxLength: 249
+    pattern: "[A-Za-z]{2}"
     example: "Ackerman Crescent"
-    description: "The street names between which the order will be delivered."
-  address: 
-    type: object
-    description: "Address of the person who will receive the order"
-    properties:
-      street1:
-        type: string
-        example: Nuevo Leon 254
-      street2: 
-        type: string
-        example: Departamento 404
-      postal_code:
-        type: string
-        example: "06100"
-      city: 
-        type: string
-        example: "Ciudad de Mexico"
-      state:
-        type: string
-        example: "Ciudad de Mexico"
-      country:
-        type: string
-        example: MX
-        description: "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)"
-      residential:
-        type: [boolean, "null"]
-        example: true
+    description: "The street names between which the order will be delivered. Must contain at least two consecutive ASCII letters."
+  address:
+    allOf:
+      - $ref: shipping_contact_address.yml
+    required:
+      - street1
+      - postal_code
+      - country
   parent_id:
     type: string
   default:

schemas/customers/customer_update_shipping_contacts.yml

@@ -11,36 +11,14 @@ properties:
     type: string
     example:   "Marvin Fuller"
     description: "Name of the person who will receive the order"
-  between_streets: 
+  between_streets:
     type: string
+    maxLength: 249
+    pattern: "[A-Za-z]{2}"
     example: "Ackerman Crescent"
-    description: "The street names between which the order will be delivered."
-  address: 
-    type: object
-    description: "Address of the person who will receive the order"
-    properties:
-      street1:
-        type: string
-        example: Nuevo Leon 254
-      street2: 
-        type: string
-        example: Departamento 404
-      postal_code:
-        type: string
-        example: "06100"
-      city: 
-        type: string
-        example: "Ciudad de Mexico"
-      state:
-        type: string
-        example: "Ciudad de Mexico"
-      country:
-        type: string
-        example: MX
-        description: "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)"
-      residential:
-        type: [boolean, "null"]
-        example: true
+    description: "The street names between which the order will be delivered. Must contain at least two consecutive ASCII letters."
+  address:
+    $ref: shipping_contact_address.yml
   parent_id:
     type: string
   default:

schemas/customers/payment_method_bnpl_request.yml

@@ -3,21 +3,20 @@ allOf:
   - $ref: './customer_payment_method_request.yml'
   - type: object
     required:
-        - can_not_expire
-        - cancel_url
         - failure_url
         - product_type
         - success_url
         - type
     properties:
       cancel_url:
-        type: string
-        description: "URL to redirect the customer after a canceled payment"
+        type: [string, "null"]
+        description: "Optional URL to redirect the customer after a canceled payment"
         example: "https://example.com/cancel"
-      can_not_expire:
-        type: boolean
-        example: true
-        description: "Indicates if the payment method can not expire"
+      expires_at:
+        type: [integer, "null"]
+        format: int64
+        example: 1680397724
+        description: "Optional expiry for the BNPL order, expressed in seconds since the Unix epoch. Defaults to one month from creation when omitted."
       failure_url:
         type: string
         description: "URL to redirect the customer after a failed payment"

schemas/customers/payment_method_card_request.yml

@@ -29,12 +29,19 @@ allOf:
         minLength: 4
       name:
         type: string
+        maxLength: 249
         example: "John Doe"
-        description: "Cardholder name"
+        description: "Cardholder name. Must include first and last name separated by a space; single-word names are rejected. Letters (including accented Latin characters), spaces, and the characters , . ' - are accepted; digits and other symbols are rejected."
       number:
         type: string
         example: "4242424242424242"
         description: "Card number"
+      contract_id:
+        type: string
+        minLength: 10
+        maxLength: 10
+        example: "3456788363"
+        description: "Optional merchant-supplied identifier (exactly 10 characters) that links a card transaction to a recurring/subscription contract at the acquiring bank. Forwarded to the bank gateway and stored on the resulting charge. Accepted on creation only; ignored on update. Do not place sensitive bank data here — the value is returned in charge responses."
       customer_ip_address:
         type: string
         example: "0.0.0.0"

schemas/customers/shipping_contact_address.yml

@@ -0,0 +1,42 @@
+title: shipping_contact_address
+type: object
+description: "Address of the person who will receive the order"
+properties:
+  street1:
+    type: string
+    minLength: 2
+    maxLength: 249
+    example: Nuevo Leon 254
+    description: "Street and number of the delivery address."
+  street2:
+    type: string
+    maxLength: 249
+    example: Departamento 404
+    description: "Apartment, suite or interior reference for the delivery address."
+  postal_code:
+    type: string
+    maxLength: 250
+    example: "06100"
+    description: "Postal code of the delivery address. For Mexican addresses (country MX) it must be a 5-digit postal code."
+  city:
+    type: string
+    maxLength: 249
+    pattern: "[A-Za-z]{2}"
+    example: "Ciudad de Mexico"
+    description: "City of the delivery address. Must contain at least two consecutive ASCII letters."
+  state:
+    type: string
+    maxLength: 249
+    example: "Ciudad de Mexico"
+    description: "State of the delivery address."
+  country:
+    type: string
+    minLength: 2
+    maxLength: 249
+    example: MX
+    description: "Country of the delivery address. This field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)."
+  residential:
+    type: [boolean, "null"]
+    default: true
+    example: true
+    description: "Indicates whether the delivery address is residential."

schemas/orders/order_request.yml

@@ -66,9 +66,15 @@ properties:
       $ref: product.yml
   metadata:
     type: object
-    additionalProperties: true
+    additionalProperties:
+      anyOf:
+        - type: string
+          maxLength: 249
+        - type: integer
+        - type: number
+        - type: boolean
     maxProperties: 100
-    description: "Metadata associated with the order"
+    description: "Metadata associated with the order. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are not supported."
   needs_shipping_contact:
     type: boolean
     example: false
@@ -98,10 +104,13 @@ properties:
     items:
       $ref: order_tax_request.yml
   three_ds_mode:
-    type: [string, "null"]
-    description: "Indicates the 3DS2 mode for the order, either smart or strict. This property is only applicable when 3DS is enabled. When 3DS is disabled, this field should be null."
+    type: string
+    enum: ["strict", "not_strict", "smart"]
+    description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. The value is validated against the allowed set on creation; sending an explicit null is rejected. Omit the field to create the order without requesting 3DS through the API (company-level 3DS applies only to orders paid through Checkout or when antifraud forces 3DS)."
     examples:
       - value: "smart"
-        summary: "Those transactions that Conekta considers to present a risk to commerce will go through an additional verification flow (through 3DS2), provided that the issuing bank is compatible with this technology.If the transaction is not considered risky, it will continue its normal course, without going through 3DS2 authentication."
+        summary: "Risk-based 3DS: transactions that Conekta considers risky go through the 3DS2 verification flow (provided the issuing bank supports it); low-risk transactions continue without 3DS2 authentication."
       - value: "strict"
-        summary: "All transactions will require 3DS2 authentication as a complementary measure for the security of charges, except those that are rejected by our Anti-Fraud. The issuing bank must be compatible with 3DS2 technology."
+        summary: "All transactions require 3DS2 authentication as a complementary security measure, except those rejected by our Anti-Fraud. The issuing bank must support 3DS2."
+      - value: "not_strict"
+        summary: "The 3DS2 flow is also always initiated, behaving like 'strict'. Acceptance of authentication attempts is governed by the company-level 3DS configuration, not by this mode."

schemas/orders/order_tax_request.yml

@@ -14,10 +14,16 @@ properties:
   description:
     type: string
     example: "testing"
-    minLength: 2
+    minLength: 3
     description: description or tax's name
   metadata:
     type: object
-    additionalProperties: true
+    additionalProperties:
+      anyOf:
+        - type: string
+          maxLength: 249
+        - type: integer
+        - type: number
+        - type: boolean
     example: { "key": "value" }
     maxProperties: 100

schemas/orders/order_update_request.yml

@@ -61,8 +61,14 @@ properties:
       $ref: product.yml
   metadata:
     type: object
+    maxProperties: 100
     additionalProperties:
-      type: string
+      anyOf:
+        - type: string
+          maxLength: 249
+        - type: integer
+        - type: number
+        - type: boolean
   pre_authorize:
     type: boolean
     description: "Indicates whether the order charges must be preauthorized"

schemas/orders/product.yml

@@ -11,22 +11,33 @@ properties:
     example: { "key": "value" }
   brand:
     type: string
+    minLength: 2
+    maxLength: 249
     example: "Cohiba"
     description: "The brand of the item."
   description:
     type: string
     example: "Imported From Mex."
-    maxLength: 250
+    minLength: 3
+    maxLength: 249
     description: "Short description of the item"
   metadata:
     type: object
     maxProperties: 100
-    description: It is a key/value hash that can hold custom fields. Maximum 100 elements and allows special characters.
-    additionalProperties: true
+    description: It is a key/value hash that can hold custom fields. Maximum 100 elements. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are not supported.
+    additionalProperties:
+      anyOf:
+        - type: string
+          maxLength: 249
+        - type: integer
+        - type: number
+        - type: boolean
     example: { "key": "value" }
     default: {}
   name:
     type: string
+    minLength: 3
+    maxLength: 249
     example: "Box of Cohiba S1s"
     description: "The name of the item. It will be displayed in the order."
   quantity:
@@ -37,12 +48,17 @@ properties:
     description: "The quantity of the item in the order."
   sku:
     type: string
+    minLength: 1
+    maxLength: 249
     example: "XYZ12345"
     description: "The stock keeping unit for the item. It is used to identify the item in the order."
   tags:
     type: array
+    minItems: 1
     items:
       type: string
+      minLength: 2
+      maxLength: 249
     example: [ "food", "mexican food"]
     description: "List of tags for the item. It is used to identify the item in the order."
   unit_price: 

schemas/orders/request_examples/charge_bnpl.yml

@@ -1,6 +1,5 @@
 value:
-  payment_method: 
-    can_not_expire: true
+  payment_method:
     cancel_url: https://pay.conekta.io/payment-status/fdcb06d6-c9e1-44ee-921f-17723b63852f/cancel
     failure_url:  https://pay.conekta.io/payment-status/fdcb06d6-c9e1-44ee-921f-17723b63852f/failure
     product_type: aplazo_bnpl

schemas/orders/request_examples/order_with_charges_bnpl.yml

@@ -6,7 +6,6 @@ value:
     checkout_request_type: "PaymentLink"
   charges:
     - payment_method:
-        can_not_expire: true
         cancel_url: "https://pay.conekta.io/payment-status/fdcb06d6-c9e1-44ee-921f-17723b63852f/cancel"
         failure_url: "https://pay.conekta.io/payment-status/fdcb06d6-c9e1-44ee-921f-17723b63852f/failure"
         product_type: "aplazo_bnpl"