From c91e43f0705cb2f9d7a59307490c67dbac318773 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Mon, 29 Jun 2026 12:56:21 -0400 Subject: [PATCH 1/6] fix(orders): tighten shipping address, line, and item schema constraints Align the OpenAPI schemas with the validations enforced by payments-api's v200 param sanitizers, which were previously under-documented. - Extract the shipping-contact address into a shared schemas/customers/shipping_contact_address.yml and reference it from the create and update shipping-contact schemas, removing the duplicated inline address blocks. - Mark street1, postal_code, and country as required on the create path (matching ShippingContacts::Validator#validate_on_create); the update path keeps them optional. - Document the MX 5-digit postal code rule and add field descriptions. - Add maxLength: 250 to address fields, shipping line carrier/tracking_number/ method, and line-item name/brand/sku and tag items. - Regenerate _build/api.yaml. Co-Authored-By: Claude Opus 4.8 (1M context) --- _build/api.yaml | 137 ++++++++++++++---- .../customers/customer_shipping_contacts.yml | 33 +---- .../customer_update_shipping_contacts.yml | 28 +--- .../customers/shipping_contact_address.yml | 39 +++++ schemas/orders/product.yml | 4 + schemas/orders/shipping_request.yml | 7 +- 6 files changed, 168 insertions(+), 80 deletions(-) create mode 100644 schemas/customers/shipping_contact_address.yml diff --git a/_build/api.yaml b/_build/api.yaml index 6ca17b4..f9218c9 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -17499,31 +17499,53 @@ components: title: customerPaymentMethods title: customer_payment_methods_response customer_shipping_contacts_request_address: - description: Address of the person who will receive the order - properties: - street1: - example: Nuevo Leon 254 - type: string - street2: - example: Departamento 404 - type: string - postal_code: - example: "06100" - type: string - city: - example: Ciudad de Mexico - type: string - state: - example: Ciudad de Mexico - type: string - country: - description: "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)" - example: MX - type: string - residential: - example: true - nullable: true - type: boolean + allOf: + - description: Address of the person who will receive the order + properties: + street1: + description: Street and number of the delivery address. + example: Nuevo Leon 254 + maxLength: 250 + type: string + street2: + description: "Apartment, suite or interior reference for the delivery\ + \ address." + example: Departamento 404 + maxLength: 250 + type: string + postal_code: + description: Postal code of the delivery address. For Mexican addresses + (country MX) it must be a 5-digit postal code. + example: "06100" + maxLength: 250 + type: string + city: + description: City of the delivery address. + example: Ciudad de Mexico + maxLength: 250 + type: string + state: + description: State of the delivery address. + example: Ciudad de Mexico + maxLength: 250 + type: string + country: + 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)." + example: MX + maxLength: 250 + type: string + residential: + default: true + description: Indicates whether the delivery address is residential. + example: true + nullable: true + type: boolean + title: shipping_contact_address + required: + - country + - postal_code + - street1 customer_shipping_contacts_data_response: allOf: - description: |- @@ -19229,14 +19251,17 @@ components: carrier: description: Carrier name for the shipment example: FEDEX + maxLength: 250 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 + maxLength: 250 type: string method: description: Method of shipment example: Same day + maxLength: 250 type: string metadata: additionalProperties: true @@ -19402,6 +19427,7 @@ components: brand: description: The brand of the item. example: Cohiba + maxLength: 250 type: string description: description: Short description of the item @@ -19420,6 +19446,7 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s + maxLength: 250 type: string quantity: description: The quantity of the item in the order. @@ -19431,6 +19458,7 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 + maxLength: 250 type: string tags: description: List of tags for the item. It is used to identify the item @@ -19439,6 +19467,7 @@ components: - food - mexican food items: + maxLength: 250 type: string type: array default: null @@ -19973,6 +20002,7 @@ components: brand: description: The brand of the item. example: Cohiba + maxLength: 250 type: string description: description: Short description of the item @@ -19991,6 +20021,7 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s + maxLength: 250 type: string quantity: description: The quantity of the item in the order. @@ -20002,6 +20033,7 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 + maxLength: 250 type: string tags: description: List of tags for the item. It is used to identify the item @@ -20010,6 +20042,7 @@ components: - food - mexican food items: + maxLength: 250 type: string type: array default: null @@ -20035,14 +20068,17 @@ components: carrier: description: Carrier name for the shipment example: FEDEX + maxLength: 250 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 + maxLength: 250 type: string method: description: Method of shipment example: Same day + maxLength: 250 type: string metadata: additionalProperties: true @@ -20279,6 +20315,7 @@ components: brand: description: The brand of the item. example: Cohiba + maxLength: 250 type: string description: description: Short description of the item @@ -20297,6 +20334,7 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s + maxLength: 250 type: string quantity: description: The quantity of the item in the order. @@ -20308,6 +20346,7 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 + maxLength: 250 type: string tags: description: List of tags for the item. It is used to identify the item @@ -20316,6 +20355,7 @@ components: - food - mexican food items: + maxLength: 250 type: string type: array default: null @@ -21320,14 +21360,17 @@ components: carrier: description: Carrier name for the shipment example: FEDEX + maxLength: 250 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 + maxLength: 250 type: string method: description: Method of shipment example: Same day + maxLength: 250 type: string metadata: additionalProperties: true @@ -21388,6 +21431,48 @@ components: example: false type: boolean title: customer_shipping_contacts_response + shipping_contact_address: + description: Address of the person who will receive the order + properties: + street1: + description: Street and number of the delivery address. + example: Nuevo Leon 254 + maxLength: 250 + type: string + street2: + description: "Apartment, suite or interior reference for the delivery address." + example: Departamento 404 + maxLength: 250 + type: string + postal_code: + description: Postal code of the delivery address. For Mexican addresses + (country MX) it must be a 5-digit postal code. + example: "06100" + maxLength: 250 + type: string + city: + description: City of the delivery address. + example: Ciudad de Mexico + maxLength: 250 + type: string + state: + description: State of the delivery address. + example: Ciudad de Mexico + maxLength: 250 + type: string + country: + 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)." + example: MX + maxLength: 250 + type: string + residential: + default: true + description: Indicates whether the delivery address is residential. + example: true + nullable: true + type: boolean + title: shipping_contact_address customer_update_shipping_contacts_request: description: |- [Shipping](https://developers.conekta.com/v2.3.0/reference/createcustomershippingcontacts) @@ -21406,7 +21491,7 @@ components: example: Ackerman Crescent type: string address: - $ref: "#/components/schemas/customer_shipping_contacts_request_address" + $ref: "#/components/schemas/shipping_contact_address" parent_id: type: string default: diff --git a/schemas/customers/customer_shipping_contacts.yml b/schemas/customers/customer_shipping_contacts.yml index d876add..be383e2 100644 --- a/schemas/customers/customer_shipping_contacts.yml +++ b/schemas/customers/customer_shipping_contacts.yml @@ -17,32 +17,13 @@ properties: type: string 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 + address: + allOf: + - $ref: shipping_contact_address.yml + required: + - street1 + - postal_code + - country parent_id: type: string default: diff --git a/schemas/customers/customer_update_shipping_contacts.yml b/schemas/customers/customer_update_shipping_contacts.yml index b26e0bf..04f74c0 100644 --- a/schemas/customers/customer_update_shipping_contacts.yml +++ b/schemas/customers/customer_update_shipping_contacts.yml @@ -15,32 +15,8 @@ properties: type: string 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 + address: + $ref: shipping_contact_address.yml parent_id: type: string default: diff --git a/schemas/customers/shipping_contact_address.yml b/schemas/customers/shipping_contact_address.yml new file mode 100644 index 0000000..5d1b44f --- /dev/null +++ b/schemas/customers/shipping_contact_address.yml @@ -0,0 +1,39 @@ +title: shipping_contact_address +type: object +description: "Address of the person who will receive the order" +properties: + street1: + type: string + maxLength: 250 + example: Nuevo Leon 254 + description: "Street and number of the delivery address." + street2: + type: string + maxLength: 250 + 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: 250 + example: "Ciudad de Mexico" + description: "City of the delivery address." + state: + type: string + maxLength: 250 + example: "Ciudad de Mexico" + description: "State of the delivery address." + country: + type: string + maxLength: 250 + 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." diff --git a/schemas/orders/product.yml b/schemas/orders/product.yml index 21b4a5f..e49c642 100644 --- a/schemas/orders/product.yml +++ b/schemas/orders/product.yml @@ -11,6 +11,7 @@ properties: example: { "key": "value" } brand: type: string + maxLength: 250 example: "Cohiba" description: "The brand of the item." description: @@ -27,6 +28,7 @@ properties: default: {} name: type: string + maxLength: 250 example: "Box of Cohiba S1s" description: "The name of the item. It will be displayed in the order." quantity: @@ -37,12 +39,14 @@ properties: description: "The quantity of the item in the order." sku: type: string + maxLength: 250 example: "XYZ12345" description: "The stock keeping unit for the item. It is used to identify the item in the order." tags: type: array items: type: string + maxLength: 250 example: [ "food", "mexican food"] description: "List of tags for the item. It is used to identify the item in the order." unit_price: diff --git a/schemas/orders/shipping_request.yml b/schemas/orders/shipping_request.yml index dad8e73..c712eff 100644 --- a/schemas/orders/shipping_request.yml +++ b/schemas/orders/shipping_request.yml @@ -8,17 +8,20 @@ properties: example: 100 minimum: 0 description: Shipping amount in cents - carrier: + carrier: type: string + maxLength: 250 example: FEDEX description: Carrier name for the shipment tracking_number: type: string + maxLength: 250 example: "TRACK123" description: Tracking number can be used to track the shipment method: type: string - example: "Same day" + maxLength: 250 + example: "Same day" description: Method of shipment metadata: description: Hash where the user can send additional information for each 'shipping'. From 5e6d4a1d009a36ba42ee607c7a8622376ec486b0 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Mon, 29 Jun 2026 13:18:03 -0400 Subject: [PATCH 2/6] fix(orders): tighten shipping address, line, and item schema constraints Align the OpenAPI schemas with the validations enforced by payments-api's v200 param sanitizers, which were previously under-documented. - Extract the shipping-contact address into a shared schemas/customers/shipping_contact_address.yml and reference it from the create and update shipping-contact schemas, removing the duplicated inline address blocks. - Mark street1, postal_code, and country as required on the create path (matching ShippingContacts::Validator#validate_on_create); the update path keeps them optional. - Document the MX 5-digit postal code rule and add field descriptions. - Add min/max length constraints matching StringValidator (strict bounds: less_than/greater_than). String fields cap at maxLength 249 (the sanitizer rejects length >= 250); minLength derives from greater_than + 1. postal_code keeps maxLength 250, its only cap being the model-level zip validation. Applies to address fields, shipping line carrier/tracking_number/method, and line-item name/description/brand/sku/tags (create and update). - Regenerate _build/api.yaml. Co-Authored-By: Claude Opus 4.8 (1M context) --- _build/api.yaml | 111 ++++++++++++------ .../customers/shipping_contact_address.yml | 12 +- schemas/orders/product.yml | 16 ++- schemas/orders/shipping_request.yml | 9 +- schemas/orders/update_product.yml | 12 +- 5 files changed, 111 insertions(+), 49 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index f9218c9..a31b7b7 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -17505,13 +17505,14 @@ components: street1: description: Street and number of the delivery address. example: Nuevo Leon 254 - maxLength: 250 + maxLength: 249 + minLength: 2 type: string street2: description: "Apartment, suite or interior reference for the delivery\ \ address." example: Departamento 404 - maxLength: 250 + maxLength: 249 type: string postal_code: description: Postal code of the delivery address. For Mexican addresses @@ -17522,18 +17523,19 @@ components: city: description: City of the delivery address. example: Ciudad de Mexico - maxLength: 250 + maxLength: 249 type: string state: description: State of the delivery address. example: Ciudad de Mexico - maxLength: 250 + maxLength: 249 type: string country: 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)." example: MX - maxLength: 250 + maxLength: 249 + minLength: 2 type: string residential: default: true @@ -19251,17 +19253,20 @@ components: carrier: description: Carrier name for the shipment example: FEDEX - maxLength: 250 + maxLength: 249 + minLength: 3 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 - maxLength: 250 + maxLength: 249 + minLength: 3 type: string method: description: Method of shipment example: Same day - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -19427,12 +19432,14 @@ components: brand: description: The brand of the item. example: Cohiba - maxLength: 250 + maxLength: 249 + minLength: 2 type: string description: description: Short description of the item example: Imported From Mex. - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -19446,7 +19453,8 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s - maxLength: 250 + maxLength: 249 + minLength: 3 type: string quantity: description: The quantity of the item in the order. @@ -19458,7 +19466,8 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 - maxLength: 250 + maxLength: 249 + minLength: 1 type: string tags: description: List of tags for the item. It is used to identify the item @@ -19467,8 +19476,10 @@ components: - food - mexican food items: - maxLength: 250 + maxLength: 249 + minLength: 2 type: string + minItems: 1 type: array default: null unit_price: @@ -20002,12 +20013,14 @@ components: brand: description: The brand of the item. example: Cohiba - maxLength: 250 + maxLength: 249 + minLength: 2 type: string description: description: Short description of the item example: Imported From Mex. - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -20021,7 +20034,8 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s - maxLength: 250 + maxLength: 249 + minLength: 3 type: string quantity: description: The quantity of the item in the order. @@ -20033,7 +20047,8 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 - maxLength: 250 + maxLength: 249 + minLength: 1 type: string tags: description: List of tags for the item. It is used to identify the item @@ -20042,8 +20057,10 @@ components: - food - mexican food items: - maxLength: 250 + maxLength: 249 + minLength: 2 type: string + minItems: 1 type: array default: null unit_price: @@ -20068,17 +20085,20 @@ components: carrier: description: Carrier name for the shipment example: FEDEX - maxLength: 250 + maxLength: 249 + minLength: 3 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 - maxLength: 250 + maxLength: 249 + minLength: 3 type: string method: description: Method of shipment example: Same day - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -20315,12 +20335,14 @@ components: brand: description: The brand of the item. example: Cohiba - maxLength: 250 + maxLength: 249 + minLength: 2 type: string description: description: Short description of the item example: Imported From Mex. - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -20334,7 +20356,8 @@ components: name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s - maxLength: 250 + maxLength: 249 + minLength: 3 type: string quantity: description: The quantity of the item in the order. @@ -20346,7 +20369,8 @@ components: description: The stock keeping unit for the item. It is used to identify the item in the order. example: XYZ12345 - maxLength: 250 + maxLength: 249 + minLength: 1 type: string tags: description: List of tags for the item. It is used to identify the item @@ -20355,8 +20379,10 @@ components: - food - mexican food items: - maxLength: 250 + maxLength: 249 + minLength: 2 type: string + minItems: 1 type: array default: null unit_price: @@ -20384,12 +20410,17 @@ components: additionalProperties: type: object description: - maxLength: 250 + maxLength: 249 + minLength: 3 type: string sku: + maxLength: 249 + minLength: 1 type: string name: example: Box of Cohiba S1s + maxLength: 249 + minLength: 3 type: string unit_price: example: 20000 @@ -20403,10 +20434,15 @@ components: type: integer tags: items: + maxLength: 249 + minLength: 2 type: string + minItems: 1 type: array default: null brand: + maxLength: 249 + minLength: 2 type: string metadata: additionalProperties: @@ -21360,17 +21396,20 @@ components: carrier: description: Carrier name for the shipment example: FEDEX - maxLength: 250 + maxLength: 249 + minLength: 3 type: string tracking_number: description: Tracking number can be used to track the shipment example: TRACK123 - maxLength: 250 + maxLength: 249 + minLength: 3 type: string method: description: Method of shipment example: Same day - maxLength: 250 + maxLength: 249 + minLength: 3 type: string metadata: additionalProperties: true @@ -21437,12 +21476,13 @@ components: street1: description: Street and number of the delivery address. example: Nuevo Leon 254 - maxLength: 250 + maxLength: 249 + minLength: 2 type: string street2: description: "Apartment, suite or interior reference for the delivery address." example: Departamento 404 - maxLength: 250 + maxLength: 249 type: string postal_code: description: Postal code of the delivery address. For Mexican addresses @@ -21453,18 +21493,19 @@ components: city: description: City of the delivery address. example: Ciudad de Mexico - maxLength: 250 + maxLength: 249 type: string state: description: State of the delivery address. example: Ciudad de Mexico - maxLength: 250 + maxLength: 249 type: string country: 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)." example: MX - maxLength: 250 + maxLength: 249 + minLength: 2 type: string residential: default: true diff --git a/schemas/customers/shipping_contact_address.yml b/schemas/customers/shipping_contact_address.yml index 5d1b44f..1b3d28a 100644 --- a/schemas/customers/shipping_contact_address.yml +++ b/schemas/customers/shipping_contact_address.yml @@ -4,12 +4,13 @@ description: "Address of the person who will receive the order" properties: street1: type: string - maxLength: 250 + minLength: 2 + maxLength: 249 example: Nuevo Leon 254 description: "Street and number of the delivery address." street2: type: string - maxLength: 250 + maxLength: 249 example: Departamento 404 description: "Apartment, suite or interior reference for the delivery address." postal_code: @@ -19,17 +20,18 @@ properties: description: "Postal code of the delivery address. For Mexican addresses (country MX) it must be a 5-digit postal code." city: type: string - maxLength: 250 + maxLength: 249 example: "Ciudad de Mexico" description: "City of the delivery address." state: type: string - maxLength: 250 + maxLength: 249 example: "Ciudad de Mexico" description: "State of the delivery address." country: type: string - maxLength: 250 + 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: diff --git a/schemas/orders/product.yml b/schemas/orders/product.yml index e49c642..3e3d196 100644 --- a/schemas/orders/product.yml +++ b/schemas/orders/product.yml @@ -11,13 +11,15 @@ properties: example: { "key": "value" } brand: type: string - maxLength: 250 + 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 @@ -28,7 +30,8 @@ properties: default: {} name: type: string - maxLength: 250 + minLength: 3 + maxLength: 249 example: "Box of Cohiba S1s" description: "The name of the item. It will be displayed in the order." quantity: @@ -39,14 +42,17 @@ properties: description: "The quantity of the item in the order." sku: type: string - maxLength: 250 + 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 - maxLength: 250 + 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: diff --git a/schemas/orders/shipping_request.yml b/schemas/orders/shipping_request.yml index c712eff..6798a9e 100644 --- a/schemas/orders/shipping_request.yml +++ b/schemas/orders/shipping_request.yml @@ -10,17 +10,20 @@ properties: description: Shipping amount in cents carrier: type: string - maxLength: 250 + minLength: 3 + maxLength: 249 example: FEDEX description: Carrier name for the shipment tracking_number: type: string - maxLength: 250 + minLength: 3 + maxLength: 249 example: "TRACK123" description: Tracking number can be used to track the shipment method: type: string - maxLength: 250 + minLength: 3 + maxLength: 249 example: "Same day" description: Method of shipment metadata: diff --git a/schemas/orders/update_product.yml b/schemas/orders/update_product.yml index c7fdd6a..9adda66 100644 --- a/schemas/orders/update_product.yml +++ b/schemas/orders/update_product.yml @@ -7,11 +7,16 @@ properties: type: object description: type: string - maxLength: 250 + minLength: 3 + maxLength: 249 sku: type: string + minLength: 1 + maxLength: 249 name: type: string + minLength: 3 + maxLength: 249 example: "Box of Cohiba S1s" unit_price: type: integer @@ -25,10 +30,15 @@ properties: minimum: 1 tags: type: array + minItems: 1 items: type: string + minLength: 2 + maxLength: 249 brand: type: string + minLength: 2 + maxLength: 249 metadata: type: object additionalProperties: From fccbdb334d353c5fcd2ae4db9d816fda120040e2 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Thu, 2 Jul 2026 14:41:02 -0400 Subject: [PATCH 3/6] fix: align checkout, order, card and bnpl schemas with enforced validations Applies verified corrections from the payments-api validator audit: - exclude_card_networks: real accepted vocabulary is [visa_master_card, amex] (exact-membership options_array validator); visa/mastercard as separate values are rejected. Responses echo stored values in CamelCase. - three_ds_mode: add the accepted value not_strict (shared constant ALLOWED_TYPES_FOR_3DS_BY_API allows strict/not_strict/smart); note the field is create-only and nullable. - metadata (orders, products, shipping/tax lines): values must be scalar string(<=249)/integer/number/boolean per nested_json_subtypes; replaces the too-loose additionalProperties:true and too-narrow {type: string}. - bnpl: cancel_url is optional by design (spec-pinned in payments-api); remove can_not_expire (not in the cleaner allowlist, silently stripped); add expires_at (the real expiry control). - card: document the enforced two-word cardholder name rule and maxLength; expose contract_id (10-char bank contract reference, create-only). - fiscal entity address: remove residential (stripped by cleaner and not storable on FiscalEntityAddress). - Rebuild _build/api.yaml. Co-Authored-By: Claude Fable 5 --- _build/api.yaml | 171 +++++++++++------- schemas/checkouts/checkout.yml | 15 +- schemas/checkouts/checkout_request.yml | 6 +- schemas/customers/customer_address.yml | 5 - .../customers/payment_method_bnpl_request.yml | 13 +- .../customers/payment_method_card_request.yml | 9 +- schemas/orders/order_request.yml | 19 +- schemas/orders/order_tax_request.yml | 8 +- schemas/orders/order_update_request.yml | 8 +- schemas/orders/product.yml | 10 +- schemas/orders/shipping_request.yml | 10 +- schemas/orders/update_order_tax_request.yml | 7 +- schemas/orders/update_product.yml | 8 +- 13 files changed, 188 insertions(+), 101 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index a31b7b7..bb860c5 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -16554,13 +16554,15 @@ components: title: customer_payment_method_request - properties: cancel_url: - description: URL to redirect the customer after a canceled payment + description: Optional URL to redirect the customer after a canceled payment example: https://example.com/cancel type: string - can_not_expire: - description: Indicates if the payment method can not expire - example: true - type: boolean + expires_at: + description: "Optional expiry for the BNPL order, expressed in seconds\ + \ since the Unix epoch" + example: 1680397724 + format: int64 + type: integer failure_url: description: URL to redirect the customer after a failed payment example: https://example.com/failure @@ -16584,8 +16586,6 @@ components: example: bnpl type: string required: - - can_not_expire - - cancel_url - failure_url - product_type - success_url @@ -16623,13 +16623,25 @@ components: minLength: 4 type: string name: - description: Cardholder name + description: Cardholder name. Must include first and last name separated + by a space; single-word names are rejected. example: John Doe + maxLength: 249 type: string number: description: Card number example: "4242424242424242" type: string + contract_id: + 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. + example: "3456788363" + maxLength: 10 + minLength: 10 + type: string customer_ip_address: description: Optional field used to capture the customer's IP address for fraud prevention and security monitoring purposes @@ -17164,10 +17176,6 @@ components: description: "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)" example: MX type: string - residential: - default: false - example: true - type: boolean external_number: type: string required: @@ -19162,6 +19170,13 @@ components: default: null description: List of discounts that are applied to the order nullable: true + order_tax_request_metadata_value: + oneOf: + - maxLength: 249 + type: string + - type: integer + - type: number + - type: boolean tax_lines_data_response: allOf: - allOf: @@ -19179,11 +19194,11 @@ components: minLength: 2 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" example: key: value maxProperties: 100 - type: object required: - amount - description @@ -19269,13 +19284,14 @@ components: minLength: 3 type: string metadata: - additionalProperties: true - description: Hash where the user can send additional information for - each 'shipping'. + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" + description: "Hash where the user can send additional information for\ + \ each 'shipping'. Values must be scalar (string of at most 249 characters,\ + \ integer, number or boolean); nested objects and arrays are rejected." example: key: value maxProperties: 100 - type: object required: - amount title: shipping_request @@ -19442,14 +19458,15 @@ components: minLength: 3 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" default: {} - description: It is a key/value hash that can hold custom fields. Maximum - 100 elements and allows special characters. + 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 rejected." example: key: value maxProperties: 100 - type: object name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s @@ -19808,15 +19825,15 @@ components: type: array default: null exclude_card_networks: - 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'. Values\ + \ are echoed back in CamelCase (e.g. 'VisaMasterCard') in responses." example: - - visa - - amex + - visa_master_card items: enum: - - visa - - mastercard + - visa_master_card - amex type: string title: checkout_request_exclude_card_networks @@ -20023,14 +20040,15 @@ components: minLength: 3 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" default: {} - description: It is a key/value hash that can hold custom fields. Maximum - 100 elements and allows special characters. + 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 rejected." example: key: value maxProperties: 100 - type: object name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s @@ -20101,13 +20119,14 @@ components: minLength: 3 type: string metadata: - additionalProperties: true - description: Hash where the user can send additional information for each - 'shipping'. + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" + description: "Hash where the user can send additional information for each\ + \ 'shipping'. Values must be scalar (string of at most 249 characters,\ + \ integer, number or boolean); nested objects and arrays are rejected." example: key: value maxProperties: 100 - type: object required: - amount title: shipping_request @@ -20126,11 +20145,11 @@ components: minLength: 2 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" example: key: value maxProperties: 100 - type: object required: - amount - description @@ -20172,10 +20191,12 @@ components: type: array default: null metadata: - additionalProperties: true - description: Metadata associated with the order + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" + 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 rejected." maxProperties: 100 - type: object needs_shipping_contact: description: Allows you to fill out the shipping information at checkout example: false @@ -20211,9 +20232,15 @@ components: type: array default: null three_ds_mode: - 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." + description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ + \ Accepted on creation only. This property is only applicable when 3DS\ + \ is enabled; when 3DS is disabled this field should be null (no 3DS flow\ + \ is applied)." + enum: + - strict + - not_strict + - smart + - null nullable: true type: string required: @@ -20294,7 +20321,8 @@ components: default: null metadata: additionalProperties: - type: string + $ref: "#/components/schemas/order_tax_request_metadata_value" + maxProperties: 100 pre_authorize: description: Indicates whether the order charges must be preauthorized type: boolean @@ -20345,14 +20373,15 @@ components: minLength: 3 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" default: {} - description: It is a key/value hash that can hold custom fields. Maximum - 100 elements and allows special characters. + 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 rejected." example: key: value maxProperties: 100 - type: object name: description: The name of the item. It will be displayed in the order. example: Box of Cohiba S1s @@ -20446,7 +20475,8 @@ components: type: string metadata: additionalProperties: - type: string + $ref: "#/components/schemas/order_tax_request_metadata_value" + maxProperties: 100 title: update_product orderRefund_request: properties: @@ -21004,16 +21034,18 @@ components: type: array default: null exclude_card_networks: - 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 request values: 'visa_master_card'\ + \ (a single token excluding both Visa and Mastercard) and 'amex'. Responses\ + \ echo the stored values in CamelCase (e.g. 'VisaMasterCard', 'Amex')." example: - - visa - - amex + - visa_master_card items: enum: - - visa - - mastercard + - visa_master_card - amex + - VisaMasterCard + - Amex type: string title: checkout_exclude_card_networks type: array @@ -21044,9 +21076,15 @@ components: type: array default: null three_ds_mode: - 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." + description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ + \ Accepted on creation only. This property is only applicable when 3DS\ + \ is enabled; when 3DS is disabled this field should be null (no 3DS flow\ + \ is applied)." + enum: + - strict + - not_strict + - smart + - null nullable: true type: string name: @@ -21412,13 +21450,14 @@ components: minLength: 3 type: string metadata: - additionalProperties: true - description: Hash where the user can send additional information for each - 'shipping'. + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" + description: "Hash where the user can send additional information for\ + \ each 'shipping'. Values must be scalar (string of at most 249 characters,\ + \ integer, number or boolean); nested objects and arrays are rejected." example: key: value maxProperties: 100 - type: object required: - amount title: shipping_request @@ -21861,11 +21900,11 @@ components: minLength: 2 type: string metadata: - additionalProperties: true + additionalProperties: + $ref: "#/components/schemas/order_tax_request_metadata_value" example: key: value maxProperties: 100 - type: object required: - amount - description @@ -21900,7 +21939,7 @@ components: type: string metadata: additionalProperties: - type: object + $ref: "#/components/schemas/order_tax_request_metadata_value" maxProperties: 100 token_request_card: properties: diff --git a/schemas/checkouts/checkout.yml b/schemas/checkouts/checkout.yml index eed957d..ff84378 100644 --- a/schemas/checkouts/checkout.yml +++ b/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 request values: 'visa_master_card' (a single token excluding both Visa and Mastercard) and 'amex'. Responses echo the stored values in CamelCase (e.g. 'VisaMasterCard', 'Amex')." items: type: string - enum: ["visa", "mastercard", "amex"] - example: ["visa", "amex"] + enum: ["visa_master_card", "amex", "VisaMasterCard", "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. This property is only applicable when 3DS is enabled; when 3DS is disabled this field should be null (no 3DS flow is applied)." 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 challenge is also always initiated; intended as the more lenient variant of 'strict' where authentication attempts may be accepted." name: type: string description: Reason for charge diff --git a/schemas/checkouts/checkout_request.yml b/schemas/checkouts/checkout_request.yml index 0f759b4..4bb3aed 100644 --- a/schemas/checkouts/checkout_request.yml +++ b/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'. Values are echoed back in CamelCase (e.g. 'VisaMasterCard') in responses." 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." diff --git a/schemas/customers/customer_address.yml b/schemas/customers/customer_address.yml index 2fe1435..ec69fcd 100644 --- a/schemas/customers/customer_address.yml +++ b/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 - \ No newline at end of file diff --git a/schemas/customers/payment_method_bnpl_request.yml b/schemas/customers/payment_method_bnpl_request.yml index 0330bf8..2296f4f 100644 --- a/schemas/customers/payment_method_bnpl_request.yml +++ b/schemas/customers/payment_method_bnpl_request.yml @@ -3,8 +3,6 @@ allOf: - $ref: './customer_payment_method_request.yml' - type: object required: - - can_not_expire - - cancel_url - failure_url - product_type - success_url @@ -12,12 +10,13 @@ allOf: properties: cancel_url: type: string - description: "URL to redirect the customer after a canceled payment" + 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 + format: int64 + example: 1680397724 + description: "Optional expiry for the BNPL order, expressed in seconds since the Unix epoch" failure_url: type: string description: "URL to redirect the customer after a failed payment" diff --git a/schemas/customers/payment_method_card_request.yml b/schemas/customers/payment_method_card_request.yml index 5b91543..9d6585d 100644 --- a/schemas/customers/payment_method_card_request.yml +++ b/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." 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" diff --git a/schemas/orders/order_request.yml b/schemas/orders/order_request.yml index ad7cd8f..57f9e55 100644 --- a/schemas/orders/order_request.yml +++ b/schemas/orders/order_request.yml @@ -66,9 +66,15 @@ properties: $ref: product.yml metadata: type: object - additionalProperties: true + additionalProperties: + oneOf: + - 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 rejected." needs_shipping_contact: type: boolean example: false @@ -99,9 +105,12 @@ properties: $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." + enum: ["strict", "not_strict", "smart", null] + description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. This property is only applicable when 3DS is enabled; when 3DS is disabled this field should be null (no 3DS flow is applied)." 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 challenge is also always initiated; intended as the more lenient variant of 'strict' where authentication attempts may be accepted." diff --git a/schemas/orders/order_tax_request.yml b/schemas/orders/order_tax_request.yml index 1c168c9..1c9b0d8 100644 --- a/schemas/orders/order_tax_request.yml +++ b/schemas/orders/order_tax_request.yml @@ -18,6 +18,12 @@ properties: description: description or tax's name metadata: type: object - additionalProperties: true + additionalProperties: + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean example: { "key": "value" } maxProperties: 100 diff --git a/schemas/orders/order_update_request.yml b/schemas/orders/order_update_request.yml index 92bd302..5c33ca2 100644 --- a/schemas/orders/order_update_request.yml +++ b/schemas/orders/order_update_request.yml @@ -61,8 +61,14 @@ properties: $ref: product.yml metadata: type: object + maxProperties: 100 additionalProperties: - type: string + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean pre_authorize: type: boolean description: "Indicates whether the order charges must be preauthorized" diff --git a/schemas/orders/product.yml b/schemas/orders/product.yml index 3e3d196..f72329f 100644 --- a/schemas/orders/product.yml +++ b/schemas/orders/product.yml @@ -24,8 +24,14 @@ properties: 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 rejected. + additionalProperties: + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean example: { "key": "value" } default: {} name: diff --git a/schemas/orders/shipping_request.yml b/schemas/orders/shipping_request.yml index 6798a9e..db58a47 100644 --- a/schemas/orders/shipping_request.yml +++ b/schemas/orders/shipping_request.yml @@ -27,8 +27,14 @@ properties: example: "Same day" description: Method of shipment metadata: - description: Hash where the user can send additional information for each 'shipping'. + description: Hash where the user can send additional information for each 'shipping'. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are rejected. type: object - additionalProperties: true + additionalProperties: + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean example: { "key": "value" } maxProperties: 100 \ No newline at end of file diff --git a/schemas/orders/update_order_tax_request.yml b/schemas/orders/update_order_tax_request.yml index eaec2e2..e8e0dc6 100644 --- a/schemas/orders/update_order_tax_request.yml +++ b/schemas/orders/update_order_tax_request.yml @@ -15,5 +15,10 @@ properties: metadata: type: object additionalProperties: - type: object + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean maxProperties: 100 diff --git a/schemas/orders/update_product.yml b/schemas/orders/update_product.yml index 9adda66..7866809 100644 --- a/schemas/orders/update_product.yml +++ b/schemas/orders/update_product.yml @@ -41,5 +41,11 @@ properties: maxLength: 249 metadata: type: object + maxProperties: 100 additionalProperties: - type: string \ No newline at end of file + oneOf: + - type: string + maxLength: 249 + - type: integer + - type: number + - type: boolean \ No newline at end of file From 477bcea936cc425aa5ca0ed6aaf70e79977d0900 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Thu, 2 Jul 2026 14:55:23 -0400 Subject: [PATCH 4/6] fix: apply adversarial-review corrections to checkout, order and metadata schemas Four skeptic reviewers re-derived every changed constraint from payments-api source. Corrections from confirmed findings: - metadata additionalProperties: oneOf -> anyOf. type integer and type number both match an integer value, so strict oneOf validators reject integers the API accepts. - exclude_card_networks: remove the CamelCase echo claim and the CamelCase enum values. The mapper camelizes only the internal checkout service payload; Checkout.to_snake_case underscores values on every read (checkout.rb:418-420), so API responses return snake_case. - order three_ds_mode: drop "accepted on creation only" (the orders cleaner permits it on update via permitted_params_shared; it is only validated on create). Checkout keeps create-only wording (its update cleaner permits nothing). - three_ds_mode null semantics: null defers to the company-level 3DS configuration; it does not disable 3DS. - not_strict description: behaviorally identical to strict in payments-api; attempt acceptance is governed by company configuration. - shipping address city: document the enforced two-consecutive-letters pattern. - card name / bnpl expires_at descriptions enriched per review. - Rebuild _build/api.yaml. Co-Authored-By: Claude Fable 5 --- _build/api.yaml | 35 +++++++++---------- schemas/checkouts/checkout.yml | 8 ++--- schemas/checkouts/checkout_request.yml | 2 +- .../customers/payment_method_bnpl_request.yml | 2 +- .../customers/payment_method_card_request.yml | 2 +- .../customers/shipping_contact_address.yml | 3 +- schemas/orders/order_request.yml | 6 ++-- schemas/orders/order_tax_request.yml | 2 +- schemas/orders/order_update_request.yml | 2 +- schemas/orders/product.yml | 2 +- schemas/orders/shipping_request.yml | 2 +- schemas/orders/update_order_tax_request.yml | 2 +- schemas/orders/update_product.yml | 2 +- 13 files changed, 35 insertions(+), 35 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index bb860c5..3cb2306 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -16559,7 +16559,7 @@ components: type: string expires_at: description: "Optional expiry for the BNPL order, expressed in seconds\ - \ since the Unix epoch" + \ since the Unix epoch. Defaults to one month from creation when omitted." example: 1680397724 format: int64 type: integer @@ -16624,7 +16624,8 @@ components: type: string name: description: Cardholder name. Must include first and last name separated - by a space; single-word names are rejected. + by a space; single-word names are rejected. Letters only — digits and + most symbols are rejected. example: John Doe maxLength: 249 type: string @@ -17529,9 +17530,11 @@ components: maxLength: 250 type: string city: - description: City of the delivery address. + description: City of the delivery address. Must contain at least two consecutive + ASCII letters. example: Ciudad de Mexico maxLength: 249 + pattern: "[A-Za-z]{2}" type: string state: description: State of the delivery address. @@ -19171,7 +19174,7 @@ components: description: List of discounts that are applied to the order nullable: true order_tax_request_metadata_value: - oneOf: + anyOf: - maxLength: 249 type: string - type: integer @@ -19827,8 +19830,7 @@ components: exclude_card_networks: 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'. Values\ - \ are echoed back in CamelCase (e.g. 'VisaMasterCard') in responses." + \ (a single token excluding both Visa and Mastercard) and 'amex'." example: - visa_master_card items: @@ -20233,9 +20235,8 @@ components: default: null three_ds_mode: description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ - \ Accepted on creation only. This property is only applicable when 3DS\ - \ is enabled; when 3DS is disabled this field should be null (no 3DS flow\ - \ is applied)." + \ The value is validated against the allowed set on creation. When this\ + \ field is null the order defers to the company-level 3DS configuration." enum: - strict - not_strict @@ -21035,17 +21036,14 @@ components: default: null exclude_card_networks: description: "List of card networks to exclude from the checkout. This field\ - \ is only applicable for card payments. Accepted request values: 'visa_master_card'\ - \ (a single token excluding both Visa and Mastercard) and 'amex'. Responses\ - \ echo the stored values in CamelCase (e.g. 'VisaMasterCard', 'Amex')." + \ is only applicable for card payments. Accepted values: 'visa_master_card'\ + \ (a single token excluding both Visa and Mastercard) and 'amex'." example: - visa_master_card items: enum: - visa_master_card - amex - - VisaMasterCard - - Amex type: string title: checkout_exclude_card_networks type: array @@ -21077,9 +21075,8 @@ components: default: null three_ds_mode: description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ - \ Accepted on creation only. This property is only applicable when 3DS\ - \ is enabled; when 3DS is disabled this field should be null (no 3DS flow\ - \ is applied)." + \ Accepted on creation only. When this field is null the checkout defers\ + \ to the company-level 3DS configuration." enum: - strict - not_strict @@ -21530,9 +21527,11 @@ components: maxLength: 250 type: string city: - description: City of the delivery address. + description: City of the delivery address. Must contain at least two consecutive + ASCII letters. example: Ciudad de Mexico maxLength: 249 + pattern: "[A-Za-z]{2}" type: string state: description: State of the delivery address. diff --git a/schemas/checkouts/checkout.yml b/schemas/checkouts/checkout.yml index ff84378..029c6b4 100644 --- a/schemas/checkouts/checkout.yml +++ b/schemas/checkouts/checkout.yml @@ -25,10 +25,10 @@ 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. Accepted request values: 'visa_master_card' (a single token excluding both Visa and Mastercard) and 'amex'. Responses echo the stored values in CamelCase (e.g. 'VisaMasterCard', 'Amex')." + 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_master_card", "amex", "VisaMasterCard", "Amex"] + enum: ["visa_master_card", "amex"] example: ["visa_master_card"] expires_at: type: integer @@ -52,14 +52,14 @@ properties: three_ds_mode: type: [string, "null"] enum: ["strict", "not_strict", "smart", null] - description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. This property is only applicable when 3DS is enabled; when 3DS is disabled this field should be null (no 3DS flow is applied)." + description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. When this field is null the checkout defers to the company-level 3DS configuration." examples: - value: "smart" 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 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 challenge is also always initiated; intended as the more lenient variant of 'strict' where authentication attempts may be accepted." + summary: "The 3DS2 challenge 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 diff --git a/schemas/checkouts/checkout_request.yml b/schemas/checkouts/checkout_request.yml index 4bb3aed..c5dcdc7 100644 --- a/schemas/checkouts/checkout_request.yml +++ b/schemas/checkouts/checkout_request.yml @@ -20,7 +20,7 @@ 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. Accepted values: 'visa_master_card' (a single token excluding both Visa and Mastercard) and 'amex'. Values are echoed back in CamelCase (e.g. 'VisaMasterCard') in responses." + 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_master_card", "amex"] diff --git a/schemas/customers/payment_method_bnpl_request.yml b/schemas/customers/payment_method_bnpl_request.yml index 2296f4f..20249a5 100644 --- a/schemas/customers/payment_method_bnpl_request.yml +++ b/schemas/customers/payment_method_bnpl_request.yml @@ -16,7 +16,7 @@ allOf: type: integer format: int64 example: 1680397724 - description: "Optional expiry for the BNPL order, expressed in seconds since the Unix epoch" + 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" diff --git a/schemas/customers/payment_method_card_request.yml b/schemas/customers/payment_method_card_request.yml index 9d6585d..4230b1a 100644 --- a/schemas/customers/payment_method_card_request.yml +++ b/schemas/customers/payment_method_card_request.yml @@ -31,7 +31,7 @@ allOf: type: string maxLength: 249 example: "John Doe" - description: "Cardholder name. Must include first and last name separated by a space; single-word names are rejected." + description: "Cardholder name. Must include first and last name separated by a space; single-word names are rejected. Letters only — digits and most symbols are rejected." number: type: string example: "4242424242424242" diff --git a/schemas/customers/shipping_contact_address.yml b/schemas/customers/shipping_contact_address.yml index 1b3d28a..2e5425d 100644 --- a/schemas/customers/shipping_contact_address.yml +++ b/schemas/customers/shipping_contact_address.yml @@ -21,8 +21,9 @@ properties: city: type: string maxLength: 249 + pattern: "[A-Za-z]{2}" example: "Ciudad de Mexico" - description: "City of the delivery address." + description: "City of the delivery address. Must contain at least two consecutive ASCII letters." state: type: string maxLength: 249 diff --git a/schemas/orders/order_request.yml b/schemas/orders/order_request.yml index 57f9e55..aa5eae1 100644 --- a/schemas/orders/order_request.yml +++ b/schemas/orders/order_request.yml @@ -67,7 +67,7 @@ properties: metadata: type: object additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer @@ -106,11 +106,11 @@ properties: three_ds_mode: type: [string, "null"] enum: ["strict", "not_strict", "smart", null] - description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. This property is only applicable when 3DS is enabled; when 3DS is disabled this field should be null (no 3DS flow is applied)." + description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. The value is validated against the allowed set on creation. When this field is null the order defers to the company-level 3DS configuration." examples: - value: "smart" 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 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 challenge is also always initiated; intended as the more lenient variant of 'strict' where authentication attempts may be accepted." + summary: "The 3DS2 challenge is also always initiated, behaving like 'strict'. Acceptance of authentication attempts is governed by the company-level 3DS configuration, not by this mode." diff --git a/schemas/orders/order_tax_request.yml b/schemas/orders/order_tax_request.yml index 1c9b0d8..ce2b0d6 100644 --- a/schemas/orders/order_tax_request.yml +++ b/schemas/orders/order_tax_request.yml @@ -19,7 +19,7 @@ properties: metadata: type: object additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer diff --git a/schemas/orders/order_update_request.yml b/schemas/orders/order_update_request.yml index 5c33ca2..65ead04 100644 --- a/schemas/orders/order_update_request.yml +++ b/schemas/orders/order_update_request.yml @@ -63,7 +63,7 @@ properties: type: object maxProperties: 100 additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer diff --git a/schemas/orders/product.yml b/schemas/orders/product.yml index f72329f..5b3beb6 100644 --- a/schemas/orders/product.yml +++ b/schemas/orders/product.yml @@ -26,7 +26,7 @@ properties: maxProperties: 100 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 rejected. additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer diff --git a/schemas/orders/shipping_request.yml b/schemas/orders/shipping_request.yml index db58a47..fdcb1c8 100644 --- a/schemas/orders/shipping_request.yml +++ b/schemas/orders/shipping_request.yml @@ -30,7 +30,7 @@ properties: description: Hash where the user can send additional information for each 'shipping'. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are rejected. type: object additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer diff --git a/schemas/orders/update_order_tax_request.yml b/schemas/orders/update_order_tax_request.yml index e8e0dc6..75db7a3 100644 --- a/schemas/orders/update_order_tax_request.yml +++ b/schemas/orders/update_order_tax_request.yml @@ -15,7 +15,7 @@ properties: metadata: type: object additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer diff --git a/schemas/orders/update_product.yml b/schemas/orders/update_product.yml index 7866809..0a2a40a 100644 --- a/schemas/orders/update_product.yml +++ b/schemas/orders/update_product.yml @@ -43,7 +43,7 @@ properties: type: object maxProperties: 100 additionalProperties: - oneOf: + anyOf: - type: string maxLength: 249 - type: integer From 7653271ade4eeeeb235785511aba6fda8afe3122 Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Thu, 2 Jul 2026 15:00:10 -0400 Subject: [PATCH 5/6] fix: describe unsupported metadata value types as contract, not enforcement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit payments-api will not change validation behavior for existing customers, so the partial per-key enforcement in NestedTypeValidator stays. State that nested objects/arrays in metadata are "not supported" rather than "rejected" — the contract is accurate without promising server-side rejection in every position. Co-Authored-By: Claude Fable 5 --- _build/api.yaml | 14 +++++++------- schemas/orders/order_request.yml | 2 +- schemas/orders/product.yml | 2 +- schemas/orders/shipping_request.yml | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index 3cb2306..7a5b40e 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -19291,7 +19291,7 @@ components: $ref: "#/components/schemas/order_tax_request_metadata_value" description: "Hash where the user can send additional information for\ \ each 'shipping'. Values must be scalar (string of at most 249 characters,\ - \ integer, number or boolean); nested objects and arrays are rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 @@ -19466,7 +19466,7 @@ components: default: {} 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 rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 @@ -20047,7 +20047,7 @@ components: default: {} 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 rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 @@ -20125,7 +20125,7 @@ components: $ref: "#/components/schemas/order_tax_request_metadata_value" description: "Hash where the user can send additional information for each\ \ 'shipping'. Values must be scalar (string of at most 249 characters,\ - \ integer, number or boolean); nested objects and arrays are rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 @@ -20197,7 +20197,7 @@ components: $ref: "#/components/schemas/order_tax_request_metadata_value" 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 rejected." + \ objects and arrays are not supported." maxProperties: 100 needs_shipping_contact: description: Allows you to fill out the shipping information at checkout @@ -20379,7 +20379,7 @@ components: default: {} 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 rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 @@ -21451,7 +21451,7 @@ components: $ref: "#/components/schemas/order_tax_request_metadata_value" description: "Hash where the user can send additional information for\ \ each 'shipping'. Values must be scalar (string of at most 249 characters,\ - \ integer, number or boolean); nested objects and arrays are rejected." + \ integer, number or boolean); nested objects and arrays are not supported." example: key: value maxProperties: 100 diff --git a/schemas/orders/order_request.yml b/schemas/orders/order_request.yml index aa5eae1..7457c15 100644 --- a/schemas/orders/order_request.yml +++ b/schemas/orders/order_request.yml @@ -74,7 +74,7 @@ properties: - type: number - type: boolean maxProperties: 100 - 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 rejected." + 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 diff --git a/schemas/orders/product.yml b/schemas/orders/product.yml index 5b3beb6..04ea0a8 100644 --- a/schemas/orders/product.yml +++ b/schemas/orders/product.yml @@ -24,7 +24,7 @@ properties: metadata: type: object maxProperties: 100 - 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 rejected. + 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 diff --git a/schemas/orders/shipping_request.yml b/schemas/orders/shipping_request.yml index fdcb1c8..b4ed8a6 100644 --- a/schemas/orders/shipping_request.yml +++ b/schemas/orders/shipping_request.yml @@ -27,7 +27,7 @@ properties: example: "Same day" description: Method of shipment metadata: - description: Hash where the user can send additional information for each 'shipping'. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are rejected. + description: Hash where the user can send additional information for each 'shipping'. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are not supported. type: object additionalProperties: anyOf: From 3fa8d05bdd2d26bf4f7c3fc5bdcd0fb9d329a85b Mon Sep 17 00:00:00 2001 From: Leo Fischer Date: Thu, 2 Jul 2026 15:22:50 -0400 Subject: [PATCH 6/6] fix: apply second adversarial-review pass corrections Five reviewers (two removal deep-dives + three full-quadrant passes) re-derived every changed line from payments-api validators, views and specs. Both questioned removals were confirmed correct: - can_not_expire (bnpl): never existed in the bnpl sanitizer (git -S empty since creation); all 26 code references are checkout/cash flows. Also cleaned the two stale bnpl request examples still sending it. - residential (fiscal address): unstorable (no Mongoid field, not in attr_accessible), stripped or blocked on every route including nested customer create, never rendered. Corrections from confirmed findings: - order three_ds_mode: explicit null is rejected (type: String check on create, empirically reproduced) -> type string, enum without null; omitting the field means no 3DS via the API (company-level 3DS applies only via Checkout or antifraud), replacing the wrong deferral claim. - checkout three_ds_mode: stays nullable (response schema) but explains null-in-responses vs omit-on-creation. - not_strict summaries: 3DS2 "flow" not "challenge" (challenge vs frictionless is issuer-side). - card name description: the regex allows , . ' - and accented letters; no longer implies punctuated names are rejected. - tax description minLength 2 -> 3 (greater_than: 2 is strict). - between_streets: document enforced maxLength 249 and two-letter pattern (city_validations). - klarna_bnpl intentionally NOT added to product_type despite being parser-accepted: not publicly available. Co-Authored-By: Claude Fable 5 --- _build/api.yaml | 40 +++++++++++-------- schemas/checkouts/checkout.yml | 4 +- .../customers/customer_shipping_contacts.yml | 6 ++- .../customer_update_shipping_contacts.yml | 6 ++- .../customers/payment_method_card_request.yml | 2 +- schemas/orders/order_request.yml | 8 ++-- schemas/orders/order_tax_request.yml | 2 +- .../orders/request_examples/charge_bnpl.yml | 3 +- .../order_with_charges_bnpl.yml | 1 - schemas/orders/update_order_tax_request.yml | 2 +- 10 files changed, 42 insertions(+), 32 deletions(-) diff --git a/_build/api.yaml b/_build/api.yaml index 7a5b40e..847c205 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -1499,7 +1499,6 @@ paths: bnpl: value: 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 @@ -1641,7 +1640,6 @@ paths: bnpl: value: 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 @@ -5073,7 +5071,6 @@ paths: 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 @@ -16623,9 +16620,10 @@ components: minLength: 4 type: string name: - description: Cardholder name. Must include first and last name separated - by a space; single-word names are rejected. Letters only — digits and - most symbols are rejected. + 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." example: John Doe maxLength: 249 type: string @@ -17575,7 +17573,10 @@ components: type: string between_streets: description: The street names between which the order will be delivered. + Must contain at least two consecutive ASCII letters. example: Ackerman Crescent + maxLength: 249 + pattern: "[A-Za-z]{2}" type: string address: $ref: "#/components/schemas/customer_shipping_contacts_request_address" @@ -17934,7 +17935,10 @@ components: type: string between_streets: description: The street names between which the order will be delivered. + Must contain at least two consecutive ASCII letters. example: Ackerman Crescent + maxLength: 249 + pattern: "[A-Za-z]{2}" type: string address: $ref: "#/components/schemas/customer_shipping_contacts_request_address" @@ -19194,7 +19198,7 @@ components: description: description: description or tax's name example: testing - minLength: 2 + minLength: 3 type: string metadata: additionalProperties: @@ -20144,7 +20148,7 @@ components: description: description: description or tax's name example: testing - minLength: 2 + minLength: 3 type: string metadata: additionalProperties: @@ -20235,14 +20239,14 @@ components: default: null three_ds_mode: description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ - \ The value is validated against the allowed set on creation. When this\ - \ field is null the order defers to the company-level 3DS configuration." + \ 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)." enum: - strict - not_strict - smart - - null - nullable: true type: string required: - currency @@ -21075,8 +21079,9 @@ components: default: null three_ds_mode: description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'.\ - \ Accepted on creation only. When this field is null the checkout defers\ - \ to the company-level 3DS configuration." + \ 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)." enum: - strict - not_strict @@ -21567,7 +21572,10 @@ components: type: string between_streets: description: The street names between which the order will be delivered. + Must contain at least two consecutive ASCII letters. example: Ackerman Crescent + maxLength: 249 + pattern: "[A-Za-z]{2}" type: string address: $ref: "#/components/schemas/shipping_contact_address" @@ -21896,7 +21904,7 @@ components: description: description: description or tax's name example: testing - minLength: 2 + minLength: 3 type: string metadata: additionalProperties: @@ -21934,7 +21942,7 @@ components: description: description: description or tax's name example: testing - minLength: 2 + minLength: 3 type: string metadata: additionalProperties: diff --git a/schemas/checkouts/checkout.yml b/schemas/checkouts/checkout.yml index 029c6b4..86b839a 100644 --- a/schemas/checkouts/checkout.yml +++ b/schemas/checkouts/checkout.yml @@ -52,14 +52,14 @@ properties: three_ds_mode: type: [string, "null"] enum: ["strict", "not_strict", "smart", null] - description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. Accepted on creation only. When this field is null the checkout defers to the company-level 3DS configuration." + 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: "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 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 challenge is also always initiated, behaving like 'strict'. Acceptance of authentication attempts is governed by the company-level 3DS configuration, not by this mode." + 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 diff --git a/schemas/customers/customer_shipping_contacts.yml b/schemas/customers/customer_shipping_contacts.yml index be383e2..979d54a 100644 --- a/schemas/customers/customer_shipping_contacts.yml +++ b/schemas/customers/customer_shipping_contacts.yml @@ -13,10 +13,12 @@ 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." + 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 diff --git a/schemas/customers/customer_update_shipping_contacts.yml b/schemas/customers/customer_update_shipping_contacts.yml index 04f74c0..a0dec2f 100644 --- a/schemas/customers/customer_update_shipping_contacts.yml +++ b/schemas/customers/customer_update_shipping_contacts.yml @@ -11,10 +11,12 @@ 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." + 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: diff --git a/schemas/customers/payment_method_card_request.yml b/schemas/customers/payment_method_card_request.yml index 4230b1a..0c703fc 100644 --- a/schemas/customers/payment_method_card_request.yml +++ b/schemas/customers/payment_method_card_request.yml @@ -31,7 +31,7 @@ allOf: type: string maxLength: 249 example: "John Doe" - description: "Cardholder name. Must include first and last name separated by a space; single-word names are rejected. Letters only — digits and most symbols are rejected." + 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" diff --git a/schemas/orders/order_request.yml b/schemas/orders/order_request.yml index 7457c15..d1ead89 100644 --- a/schemas/orders/order_request.yml +++ b/schemas/orders/order_request.yml @@ -104,13 +104,13 @@ properties: items: $ref: order_tax_request.yml three_ds_mode: - type: [string, "null"] - enum: ["strict", "not_strict", "smart", null] - description: "Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. The value is validated against the allowed set on creation. When this field is null the order defers to the company-level 3DS configuration." + 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: "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 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 challenge is also always initiated, behaving like 'strict'. Acceptance of authentication attempts is governed by the company-level 3DS configuration, not by this mode." + 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." diff --git a/schemas/orders/order_tax_request.yml b/schemas/orders/order_tax_request.yml index ce2b0d6..8cdd6e0 100644 --- a/schemas/orders/order_tax_request.yml +++ b/schemas/orders/order_tax_request.yml @@ -14,7 +14,7 @@ properties: description: type: string example: "testing" - minLength: 2 + minLength: 3 description: description or tax's name metadata: type: object diff --git a/schemas/orders/request_examples/charge_bnpl.yml b/schemas/orders/request_examples/charge_bnpl.yml index 5bd311a..0af6aed 100644 --- a/schemas/orders/request_examples/charge_bnpl.yml +++ b/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 diff --git a/schemas/orders/request_examples/order_with_charges_bnpl.yml b/schemas/orders/request_examples/order_with_charges_bnpl.yml index fce1192..8138419 100644 --- a/schemas/orders/request_examples/order_with_charges_bnpl.yml +++ b/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" diff --git a/schemas/orders/update_order_tax_request.yml b/schemas/orders/update_order_tax_request.yml index 75db7a3..68f2767 100644 --- a/schemas/orders/update_order_tax_request.yml +++ b/schemas/orders/update_order_tax_request.yml @@ -10,7 +10,7 @@ properties: description: type: string example: "testing" - minLength: 2 + minLength: 3 description: description or tax's name metadata: type: object