{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.connect.worldline-solutions.com/2026-04-08/schema.json",
  "title": "Worldline GlobalCollect Payment Handler — Schema",
  "description": "Schema-only document for the com.worldline.globalcollect UCP payment handler, built against the UCP 2026-04-08 payment-handler guide. Defines the three handler-declaration variants (business_schema, platform_schema, response_schema) and the card / redirect / mobile instrument and credential shapes. The accompanying flows, processing, error handling and security live in the separate payment-handler spec document. Scope: card (raw card and externally provisioned network token), redirect (APM), and mobile (wallet) instruments. The set of products actually enabled for a given Business is advertised in the discovery profile's available_instruments. Worldline credentials (merchant_id, API keys) are held by the Business server-side and never appear in the discovery profile.",
  "name": "com.worldline.globalcollect",
  "version": "2026-04-08",

  "$defs": {
    "com.worldline.globalcollect": {
      "title": "com.worldline.globalcollect handler types",
      "description": "Consumable handler types. payment_instrument is the oneOf the Platform submits on checkout-complete; offered_instrument is how a payable product appears in the create-checkout response (an entry in the standard UCP payment.instruments[]); the three *_schema variants are the handler declaration as it appears in business discovery, the platform profile, and the runtime checkout/order response respectively.",
      "type": "object",
      "properties": {
        "payment_instrument": {
          "title": "Worldline Connect Payment Instrument",
          "description": "An acquired instrument the Platform submits to the Business via UCP. Exactly one of the card / redirect / mobile shapes.",
          "oneOf": [
            { "$ref": "#/$defs/worldline_card_instrument" },
            { "$ref": "#/$defs/worldline_redirect_instrument" },
            { "$ref": "#/$defs/worldline_mobile_instrument" }
          ]
        },
        "offered_instrument": {
          "title": "Worldline Connect Offered Instrument",
          "description": "How the Business presents a payable Worldline product to the Platform at create-checkout time, as an entry in the checkout response's payment.instruments[] array (UCP's standard field — there is no separate offered_instruments field). Carries the product the buyer may select plus any additional input fields resolved at checkout time. selected is false until the Platform chooses it.",
          "$ref": "#/$defs/offered_payment_instrument"
        },
        "business_schema": {
          "title": "Worldline Connect — Business Handler Declaration",
          "description": "How the Business advertises this handler in its UCP discovery profile (/.well-known/ucp). Composes the base PaymentHandler business_schema with the Worldline business_config.",
          "allOf": [
            { "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/business_schema" },
            {
              "type": "object",
              "properties": {
                "config": { "$ref": "#/$defs/business_config" }
              }
            }
          ]
        },
        "platform_schema": {
          "title": "Worldline Connect — Platform Handler Declaration",
          "description": "How the Platform declares support for this handler in its profile. Composes the base PaymentHandler platform_schema with the Worldline platform_config.",
          "allOf": [
            { "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/platform_schema" },
            {
              "type": "object",
              "properties": {
                "config": { "$ref": "#/$defs/platform_config" }
              }
            }
          ]
        },
        "response_schema": {
          "title": "Worldline Connect — Runtime Response Declaration",
          "description": "How the handler appears in UCP checkout/order API responses. Platforms MUST treat this as authoritative. Composes the base PaymentHandler response_schema with the Worldline response_config.",
          "allOf": [
            { "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/response_schema" },
            {
              "type": "object",
              "properties": {
                "config": { "$ref": "#/$defs/response_config" }
              }
            }
          ]
        }
      }
    },

    "business_config": {
      "title": "Worldline Connect — Business Configuration",
      "description": "Configuration the Business carries for this handler in the discovery profile. Only the (non-secret) environment selector is surfaced. The Worldline merchant_id and API credentials are internal to the Business, held server-side, and are deliberately NOT part of the discovery profile.",
      "type": "object",
      "properties": {
        "environment": {
          "type": "string",
          "enum": ["sandbox", "production"],
          "default": "sandbox",
          "description": "Worldline Connect environment this handler targets."
        }
      },
      "additionalProperties": false
    },

    "platform_config": {
      "title": "Worldline Connect — Platform Configuration",
      "description": "Empty for this handler. The Platform does not configure anything specific to Worldline Connect; Worldline credentials and policy live with the Business.",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    },

    "response_config": {
      "title": "Worldline Connect — Runtime Response Configuration",
      "description": "Empty for this handler. Buyer handoff for redirect-product approval (e.g. iDEAL, PayPal) and for card 3DS challenges uses the built-in UCP checkout escalation mechanism, not a handler-specific field: the Business sets the checkout `status` to `requires_escalation`, puts the Worldline approval/authentication URL in the standard top-level `continue_url`, and adds a `messages` entry with severity `requires_buyer_input`. See https://ucp.dev/2026-04-08/specification/checkout/#status-values.",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    },

    "worldline_card_instrument": {
      "title": "Worldline Connect Card Instrument",
      "description": "Card instrument. Extends the base UCP card_payment_instrument (id, handler_id, type, billing_address, credential, display) with the Worldline product id and card credential.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/card_payment_instrument.json" }
      ],
      "type": "object",
      "required": ["type", "payment_product_id", "credential"],
      "properties": {
        "type": { "const": "card" },
        "payment_product_id": {
          "type": "integer",
          "description": "Worldline product ID (e.g. 1=Visa, 2=Amex, 3=Mastercard). See available_instruments for the products currently enabled."
        },
        "credential": { "$ref": "#/$defs/worldline_card_credential" }
      }
    },

    "worldline_redirect_instrument": {
      "title": "Worldline Connect Redirect Instrument",
      "description": "Redirect (alternative payment method) instrument. Extends the base UCP payment_instrument with the Worldline product id and redirect credential.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json" }
      ],
      "type": "object",
      "required": ["type", "payment_product_id", "credential"],
      "properties": {
        "type": { "const": "redirect" },
        "payment_product_id": {
          "type": "integer",
          "description": "Worldline product ID (e.g. 809=iDEAL/WERO, 840=PayPal). See available_instruments for the products currently enabled."
        },
        "credential": { "$ref": "#/$defs/worldline_redirect_credential" }
      }
    },

    "worldline_mobile_instrument": {
      "title": "Worldline Connect Mobile Instrument",
      "description": "Mobile / wallet instrument. Extends the base UCP payment_instrument with the Worldline product id and mobile credential.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json" }
      ],
      "type": "object",
      "required": ["type", "payment_product_id", "credential"],
      "properties": {
        "type": { "const": "mobile" },
        "payment_product_id": {
          "type": "integer",
          "description": "Worldline product ID (e.g. 320=Google Pay, 302=Apple Pay). See available_instruments for the products currently enabled."
        },
        "credential": { "$ref": "#/$defs/worldline_mobile_credential" }
      }
    },

    "offered_payment_instrument": {
      "title": "Worldline Connect Offered Payment Instrument",
      "description": "An offered Worldline instrument returned in the UCP create-checkout response under payment.instruments[]. Extends the base UCP payment_instrument (id, handler_id, type, display, selected) with the Worldline product id and the additional input fields resolved at checkout time. It MUST remain a valid UCP payment_instrument (correct base fields) or the Platform will ignore it; payment_product_id and product_fields are handler extensions that handler-aware Platforms read. No credential is present yet — the Platform collects the fields and submits the corresponding payment_instrument (with credential) on checkout-complete.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json" }
      ],
      "type": "object",
      "required": ["type", "payment_product_id"],
      "properties": {
        "type": {
          "enum": ["card", "redirect", "mobile"],
          "description": "The offered instrument type."
        },
        "payment_product_id": {
          "type": "integer",
          "description": "The Worldline product the Platform may select for this checkout."
        },
        "product_fields": {
          "type": "array",
          "description": "Additional input fields the buyer MUST provide for this product, resolved at create-checkout time by the Business from the Worldline Connect Get Payment Product Fields API (GET /v1/{merchantId}/products/{paymentProductId}). These fall outside the default *PaymentMethodSpecificInput shapes carried in the submitted credential. Each item is a normalized, self-contained field descriptor (see product_field) — the Business maps the Worldline field definition into this shape rather than exposing the Worldline OpenAPI definition directly. Absent or empty when the product needs no extra input. The Platform renders/validates these and places the collected values in the submitted credential, keyed by the field id.",
          "items": { "$ref": "#/$defs/product_field" }
        }
      }
    },

    "product_field": {
      "title": "Worldline Connect Product Field",
      "description": "A normalized, self-contained descriptor for one additional input field the buyer must supply for a product. The Business derives it from the Worldline Connect Get Payment Product Fields API but expresses it independently of the Worldline OpenAPI definitions, so Platforms integrate against this handler schema alone. The Platform renders the field, validates against the constraints, and submits the collected value under id in the credential.",
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Field key. The Platform submits the collected value under this key in the credential."
        },
        "type": {
          "type": "string",
          "enum": ["string", "numeric", "integer", "boolean", "date", "expiry_date", "currency"],
          "description": "Input data type — used to pick the control and coarse validation."
        },
        "label": {
          "type": "string",
          "description": "Human-readable label to display to the buyer."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "Whether the buyer must provide a value."
        },
        "constraints": {
          "type": "object",
          "description": "Optional validation constraints for free-form input.",
          "properties": {
            "min_length": { "type": "integer", "description": "Minimum value length." },
            "max_length": { "type": "integer", "description": "Maximum value length." },
            "pattern": { "type": "string", "description": "Regular expression the value must match." }
          },
          "additionalProperties": false
        },
        "options": {
          "type": "array",
          "description": "Allowed values for an enumerated field (e.g. the issuer list for a bank redirect). Omit for free-form fields.",
          "items": {
            "type": "object",
            "required": ["value"],
            "properties": {
              "value": { "type": "string", "description": "Value submitted in the credential." },
              "label": { "type": "string", "description": "Display label for this option." }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },

    "worldline_card_credential": {
      "title": "Worldline Connect Card Credential",
      "description": "Carried in payment_instrument.credential when type is worldline_card. Reuses the Worldline Connect CardPaymentMethodSpecificInput as the single source of truth for card fields — it covers both raw card (card) and externally provisioned network token (networkTokenData), the two supported acquisition modes. UCP additions only: the type discriminator and the credential binding.",
      "type": "object",
      "required": ["type"],
      "allOf": [
        { "$ref": "https://apireference.connect.worldline-solutions.com/openapi.json#/components/schemas/CardPaymentMethodSpecificInput" }
      ],
      "properties": {
        "type": {
          "const": "worldline_connect_card",
          "description": "Discriminator for this credential shape."
        },
        "binding": { "$ref": "#/$defs/binding" }
      }
    },

    "worldline_redirect_credential": {
      "title": "Worldline Connect Redirect Credential",
      "description": "Carried in payment_instrument.credential when type is worldline_redirect. Reuses the Worldline Connect RedirectPaymentMethodSpecificInput as the single source of truth — it carries redirectionData (incl. returnUrl) and the product-specific input branches (iDEAL, PayPal, Klarna, etc.). UCP additions only: the type discriminator and the credential binding.",
      "type": "object",
      "required": ["type"],
      "allOf": [
        { "$ref": "https://apireference.connect.worldline-solutions.com/openapi.json#/components/schemas/RedirectPaymentMethodSpecificInput" }
      ],
      "properties": {
        "type": {
          "const": "worldline_connect_redirect",
          "description": "Discriminator for this credential shape."
        },
        "binding": { "$ref": "#/$defs/binding" }
      }
    },

    "worldline_mobile_credential": {
      "title": "Worldline Connect Mobile Credential",
      "description": "Carried in payment_instrument.credential when type is worldline_mobile. Reuses the Worldline Connect MobilePaymentMethodSpecificInput as the single source of truth — it carries the encrypted/decrypted wallet payment data and product-specific input (e.g. Google Pay product 320). UCP additions only: the type discriminator and the credential binding.",
      "type": "object",
      "required": ["type"],
      "allOf": [
        { "$ref": "https://apireference.connect.worldline-solutions.com/openapi.json#/components/schemas/MobilePaymentMethodSpecificInput" }
      ],
      "properties": {
        "type": {
          "const": "worldline_connect_mobile",
          "description": "Discriminator for this credential shape."
        },
        "binding": { "$ref": "#/$defs/binding" }
      }
    },

    "available_worldline_card": {
      "title": "Available Worldline Connect Card",
      "description": "Card availability with Worldline-specific constraints, as advertised in a payment_handlers[].available_instruments entry. Extends the base available_card_payment_instrument.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/card_payment_instrument.json#/$defs/available_card_payment_instrument" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "card" },
            "constraints": {
              "type": "object",
              "properties": {
                "brands": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "Card brands enabled for this Business (e.g. visa, mastercard, amex)."
                },
                "acquisition_modes": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": ["raw_card", "network_token"]
                  },
                  "description": "How the Platform may acquire a card credential for this Business."
                }
              }
            }
          }
        }
      ]
    },

    "available_worldline_redirect": {
      "title": "Available Worldline Connect Redirect",
      "description": "Redirect availability with Worldline-specific constraints. Extends the base available_payment_instrument.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/available_payment_instrument.json" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "redirect" },
            "constraints": {
              "type": "object",
              "properties": {
                "products": {
                  "type": "array",
                  "description": "Redirect products enabled for this Business.",
                  "items": { "$ref": "#/$defs/product_entry" }
                }
              }
            }
          }
        }
      ]
    },

    "available_worldline_mobile": {
      "title": "Available Worldline Connect Mobile",
      "description": "Mobile / wallet availability with Worldline-specific constraints. Extends the base available_payment_instrument.",
      "allOf": [
        { "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/available_payment_instrument.json" },
        {
          "type": "object",
          "properties": {
            "type": { "const": "mobile" },
            "constraints": {
              "type": "object",
              "properties": {
                "products": {
                  "type": "array",
                  "description": "Mobile / wallet products enabled for this Business.",
                  "items": { "$ref": "#/$defs/product_entry" }
                }
              }
            }
          }
        }
      ]
    },

    "product_entry": {
      "title": "Enabled product entry",
      "description": "A single payment product the Business has enabled, as advertised in available_instruments at discovery time. This is a static, pre-checkout declaration of which products exist; it deliberately carries no field shapes. The default input fields for a product come from the reused Worldline OpenAPI *PaymentMethodSpecificInput schemas, and any additional product-specific input fields are resolved at create-checkout time from the Worldline Connect Get Payment Product Fields API and surfaced on the offered instrument's product_fields (see com.worldline.globalcollect.offered_instrument and the payment-handler spec).",
      "type": "object",
      "required": ["id"],
      "properties": {
        "id": { "type": "integer", "description": "Worldline product ID." },
        "name": { "type": "string", "description": "Display label." },
        "countries": {
          "type": "array",
          "items": { "type": "string" },
          "description": "ISO 3166-1 alpha-2 country codes the product is offered in (e.g. NL). Omit when unconstrained."
        },
        "currencies": {
          "type": "array",
          "items": { "type": "string" },
          "description": "ISO 4217 currency codes the product supports (e.g. EUR). Omit when unconstrained."
        }
      }
    },

    "binding": {
      "title": "UCP Credential Binding",
      "description": "Binds a credential to a single UCP checkout and identity to prevent reuse. The Business MUST verify these match the active checkout before treating the credential as authoritative. Network tokens are additionally scoped to the Business's merchant account; redirect / 3DS flows use RETURNMAC, issued at initiation and validated (constant-time) on return.",
      "type": "object",
      "required": ["checkout_id", "identity"],
      "properties": {
        "checkout_id": {
          "type": "string",
          "description": "The UCP checkout_id this credential was acquired for."
        },
        "identity": {
          "type": "string",
          "description": "The UCP identity (access token / buyer identity) this credential is bound to."
        }
      }
    }
  }
}