Worldline Global Collect payment handler

• Handler Name: com.worldline.connect
• Version: 2026-04-08

Overview

The Worldline Connect payment handler defines how a business (You) that processes payments through Worldline Connect (the GlobalCollect platform) interoperates with Universal Commerce Protocol Platforms. It supports three instrument types — card, redirect (alternative payment methods), and mobile (wallets) — covering raw card, externally provisioned network token, redirect-product, and wallet acquisition flows.

The Platform interacts only with your Universal Commerce Protocol endpoints. You hold your Worldline credentials server-side and translate Universal Commerce Protocol calls into Worldline Connect Server API calls; the Platform never calls Worldline directly. The concrete products enabled for a given business are advertised in available_instruments in its discovery profile — this document describes instrument types, not named products.

The configuration, instrument, and credential shapes referenced here are defined in the companion schema: worldline-connect-payment-handler-schema.json.

Key benefits

• Primary Account Number (PAN) stays off platform servers: Card acquisition by network token carries no Primary Account Number (PAN), and wallet tokens are encrypted by the wallet provider. Raw card data is supported only for PCI-DSS-compliant server-to-server integrations.
• Minimal platform configuration: The platform learns everything it needs from available_instruments; Worldline credentials (including merchant_id) never leave the Business (You).
• Stable Universal Commerce Protocol surface: Worldline-specific request/response shapes stay behind the Business (You) — the Platform only ever sees Universal Commerce Protocol checkout/order state. Buyer handoff for redirect approval and 3DS uses the built-in Universal Commerce Protocol requires_escalation status and continue_url, so there is no handler-specific redirect field for the Platform to special-case.

Integration Guide

Participants

   Buyer
     │ acquires credential (token / wallet / redirect)
     ▼
  Platform ──── Universal Commerce Protocol (discovery, checkout, complete) ────► Business (You)
                                                             │ Worldline Connect Server API
                                                             ▼
                                                      Worldline Connect (Payment Service Provider)
                                                             │ webhook events
                                                             ▼
                                                          Business (You)

Business integration

Before advertising this handler, you need to:

1. Create a Worldline Connect account and obtain merchant_id, api_key_id, and api_secret.
2. Enable the desired card, redirect, and mobile payment products in the Worldline Configuration Center.

Handler configuration

Handler Schema

Schema URL: {{SCHEMA_BASE_URL}}/worldline-connect-payment-handler-schema.json

The schema composes the base Universal Commerce Protocol payment_handler.json declaration variants with Worldline-specific configuration:

Business configuration fields

Response configuration fields

response_config is empty. Buyer handoff is not carried by a handler-specific field — it uses the built-in Universal Commerce Protocol checkout escalation mechanism:

Example handler declaration

How a business advertises this handler in its Universal Commerce Protocol discovery profile under payment_handlers. Product IDs and brands below are illustrative — each business fills in the products it has enabled:

{
  "version": "2026-04-08",
  "payment_handlers": {
    "com.worldline.connect": [
      {
        "id": "worldline_connect",
        "version": "2026-04-08",
        "spec": "./worldline-connect-payment-handler-spec.md",
        "schema": "./worldline-connect-payment-handler-schema.json",
        "available_instruments": [
          {
            "type": "card",
            "constraints": {
              "brands": ["visa", "mastercard", "amex"],
              "acquisition_modes": ["raw_card", "network_token"]
            }
          },
          {
            "type": "redirect",
            "constraints": {
              "products": [
                { "id": 809, "name": "iDEAL / WERO", "countries": ["NL"], "currencies": ["EUR"] },
                { "id": 840, "name": "PayPal" }
              ]
            }
          },
          {
            "type": "mobile",
            "constraints": {
              "products": [
                { "id": 320, "name": "Google Pay" }
              ]
            }
          }
        ]
      }
    ]
  }
}

The handler name is the registry key (com.worldline.connect); the entry uses id / name / version / spec / single schema / config plus available_instruments. A single schema URL covers the configuration, instrument, and credential shapes. config carries only the non-secret environment.

Processing payments

Upon receiving a payment with this handler's instrument on checkout-complete, you need to:

1. Validate handler. Confirm instrument.handler_id matches the advertised handler (worldline_connect). Reject instruments addressed to a different handler.
2. Ensure idempotency. Key processing on the checkout_id / idempotency key and send Worldline's X-GCS-Idempotence-Key. On a retry that matches a prior request, return the previous result without re-processing funds.
3. Verify binding. Verify the credential's binding matches the active checkout and identity (see Security considerations): checkout_id and identity must match the active checkout; network tokens must belong to this merchant_id.
4. Create payment. Map the Universal Commerce Protocol credential to a Worldline CreatePaymentRequest and call POST /v1/{merchantId}/payments. The credential reuses the Worldline OpenAPI *PaymentMethodSpecificInput schema for its instrument type, so the mapping is direct:

• card → CardPaymentMethodSpecificInput (networkTokenData for network tokens, or raw card.*)
• redirect → RedirectPaymentMethodSpecificInput (incl. redirectionData.returnUrl)
• mobile → MobilePaymentMethodSpecificInput (encrypted/decrypted wallet data)

1. Escalate for buyer handoff. If Worldline returns merchantAction = REDIRECT (a 3DS challenge or a redirect-product approval), use the built-in Universal Commerce Protocol escalation mechanism: set the checkout status to requires_escalation, put the Worldline redirect URL (merchantAction.redirectData.redirectURL) in the standard top-level continue_url, and add a messages entry with severity requires_buyer_input.
2. Reconcile. Resolve the final payment state via webhooks (preferred) or a GET /payments/{paymentId} fallback, then propagate to Universal Commerce Protocol checkout/order state.
3. Return response. Respond with the finalized Universal Commerce Protocol checkout state. Worldline errors are mapped to Universal Commerce Protocol errors (the Platform never sees Worldline error shapes):

Platform integration

Before using this handler, the Platform needs to:

1. Fetch your Universal Commerce Protocol discovery profile (/.well-known/ucp).
2. Confirm com.worldline.connect appears in payment_handlers and inspect its available_instruments to learn which instrument types and products are supported.

Handler configuration

Platform configuration fields

Example platform handler declaration

{
  "version": "2026-04-08",
  "payment_handlers": {
    "com.worldline.connect": [
      {
        "id": "worldline_connect",
        "version": "2026-04-08",
        "spec": "./worldline-connect-payment-handler-spec.md",
        "schema": "./worldline-connect-payment-handler-schema.json",
        "config": {}
      }
    ]
  }
}

Payment protocol

The platform needs to follow this flow to acquire and submit a payment instrument:

Step 1: Discover handler

Identify com.worldline.connect in your Universal Commerce Protocol discovery profile and read available_instruments to learn which instrument types and products you support. Discovery lists products only (id, name, optional countries / currencies) and carries no field shapes. The fields a buyer must supply for a given product are resolved at create-checkout time (Step 2).

Step 2: Initiate checkout

Call the business's Universal Commerce Protocol checkout-create endpoint. The business — server-side, with its own credentials — determines which enabled products are eligible for this checkout (Worldline filters on amount, country, and currency) and returns the eligible subset as offered instruments in the standard Universal Commerce Protocol payment.instruments[] array (each with selected: false).

For each offered product the business calls Worldline's Get Payment Product Fields API (GET /v1/{merchantId}/products/{paymentProductId}) and places any additional required input fields — those that fall outside the default *PaymentMethodSpecificInput shapes — on the offered instrument's product_fields array. Each entry is a normalized product_field descriptor defined by this handler schema (id, type, label, required, constraints, options); the business maps the Worldline field definition into it rather than exposing the Worldline OpenAPI definition directly.

Each offered instrument needs to be a valid Universal Commerce Protocol payment_instrument (id, handler_id, type); payment_product_id and product_fields are handler extensions. There is no separate offered_instruments field — Universal Commerce Protocol carries them in payment.instruments[], so a Platform that does not recognise the extension still sees valid instruments (and ignores ones it cannot parse).

{
  "payment": {
    "instruments": [
      {
        "id": "offer_redirect_809",
        "handler_id": "worldline_connect",
        "type": "redirect",
        "payment_product_id": 809,
        "display": { "name": "iDEAL / WERO" },
        "product_fields": [
          {
            "id": "issuerId",
            "type": "string",
            "label": "Bank",
            "required": true,
            "options": [
              { "value": "INGBNL2A", "label": "ING" },
              { "value": "RABONL2U", "label": "Rabobank" }
            ]
          }
        ],
        "selected": false
      }
    ]
  }
}

Step 3: Acquire the credential

Acquire the credential for the chosen instrument type. The submitted credential reuses the Worldline OpenAPI *PaymentMethodSpecificInput schema (the single source of truth for its fields) plus the Universal Commerce Protocol type discriminator and binding:

• Card (type: worldline_connect_card):
  • Network token (preferred). Submit an externally provisioned network token via networkTokenData. Network tokens typically authenticate frictionless (no buyer challenge) due to their stronger risk signals, though the issuer may still trigger a challenge.
  • Raw card. Submit raw card.* data — server-to-server, PCI-DSS-compliant integrations only (e.g. sandbox test cards). May trigger a 3DS challenge.
• Redirect (type: worldline_connect_redirect): populate RedirectPaymentMethodSpecificInput for the chosen payment_product_id, including redirectionData.returnUrl and any product-specific input branch (iDEAL, PayPal, etc.).
• Mobile (type: worldline_connect_mobile): obtain the encrypted wallet token from the wallet provider's API on the buyer's device and populate MobilePaymentMethodSpecificInput.

In addition, collect any values listed in the chosen offered instrument's product_fields (from Step 2) and place them in the submitted credential alongside the reused *PaymentMethodSpecificInput fields.

Step 4: Bind the credential

Include a binding object on the credential carrying the checkout_id and identity the credential was acquired for. This binds the credential to a single checkout and prevents reuse.

Step 5: Handle escalation (if required)

If the checkout response has status: requires_escalation (redirect-product approval or a card 3DS challenge), redirect the buyer to the standard top-level continue_url. This is the built-in Universal Commerce Protocol handoff — there is no handler-specific redirect field. The buyer returns to the configured return URL, after which the Business (You) resolves the final payment state and the checkout transitions to ready_for_complete / completed.

Step 6: Complete checkout

Submit the selected instrument to the Business:

POST /checkout-sessions/{checkout_id}/complete
Content-Type: application/json

{
  "payment": {
    "instruments": [
      {
        "id": "inst_1",
        "handler_id": "worldline_connect",
        "type": "card",
        "payment_product_id": 1,
        "selected": true,
        "credential": {
          "type": "worldline_connect_card",
          "networkTokenData": { /* CardPaymentMethodSpecificInput fields */ },
          "binding": { "checkout_id": "chk_123", "identity": "buyer_abc" }
        }
      }
    ]
  }
}

Payment Service Provider integration (Worldline Connect)

Worldline-specific details you need when implementing this handler.

• Server API base URLs. Sandbox: https://api.preprod.connect.worldline-solutions.com · Production: https://api.connect.worldline-solutions.com. Selected server-side via the Business (You)'s config.environment.
• Payment products. payment_product_id values identify the Worldline product for each instrument type (e.g. card 1=Visa, 3=Mastercard; redirect 809=iDEAL/WERO, 840=PayPal; mobile 320=Google Pay, 302=Apple Pay). The enabled set is advertised in available_instruments.
• Product-specific input. Default per-method fields come from the reused Worldline OpenAPI *PaymentMethodSpecificInput schemas (carried in the submitted credential). Some products need additional fields (e.g. an issuer for a bank redirect, or a cardholder name for a wallet's browser 3DS flow). The Business (You) resolves these at create-checkout time via the Worldline Get Payment Product Fields API (GET /v1/{merchantId}/products/{paymentProductId}) and surfaces them on the offered instrument's product_fields in the checkout response (see Platform Integration, Step 2). Discovery carries no field shapes — only the product list.
• OpenAPI source of truth. Credential shapes reuse the Worldline Connect OpenAPI *PaymentMethodSpecificInput definitions (the schema references them via the {{PLACEHOLDER}} base location) rather than restating their fields.
• Idempotency. Worldline supports X-GCS-Idempotence-Key on Create Payment (retained ~24h; an in-flight duplicate returns HTTP 409).
• Webhooks. Worldline emits signed webhook events; the Business (You) verifies signatures with webhook_key_id / webhook_secret and reconciles them to Universal Commerce Protocol state.

Security considerations

References

• Handler Spec (this document): {{SCHEMA_BASE_URL}}/worldline-connect-payment-handler-spec.md
• Handler Schema (configuration, instrument, and credential shapes): {{SCHEMA_BASE_URL}}/worldline-connect-payment-handler-schema.json
• Universal Commerce Protocol Payment Handler Template: https://ucp.dev/2026-04-08/specification/payment-handler-template/
• Worldline Connect docs: https://docs.connect.worldline-solutions.com