Worldline Global Collect payment handler

• Handler name: com.worldline.globalcollect
• Version: 2026-04-08

Overview

The Worldline Global Collect payment handler defines how a business (You) that processes payments through the Worldline Global Collect 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 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-globalcollect-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 Global Collect (Payment Service Provider)
                                                             │ webhook events
                                                             ▼
                                                          Business (You)

Business integration

As the Business, you need to complete these prerequisites before advertising this handler:

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: https://ucp.connect.worldline-solutions.com/2026-04-08/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

The response_config is empty. Buyer handoff uses the built-in Universal Commerce Protocol checkout escalation mechanism, not a handler-specific field:

Example handler declaration

How you advertise this handler in your Universal Commerce Protocol discovery profile under payment_handlers. Product IDs and brands below are illustrative; fill in the products you have enabled:

{
  "version": "2026-04-08",
  "payment_handlers": {
    "com.worldline.globalcollect": [
      {
        "id": "worldline_globalcollect",
        "version": "2026-04-08",
        "spec": "https://ucp.connect.worldline-solutions.com/gc-payment-handler.md",
        "schema": "https://ucp.connect.worldline-solutions.com/2026-04-08/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.globalcollect); the entry uses id / 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

When you receive a payment with this handler's instrument on checkout-complete, follow these steps:

1. Validate handler - Confirm instrument.handler_id matches the advertised handler (worldline_globalcollect). Reject instruments addressed to a different handler.
2. Ensure idempotency - Key processing on the checkout_id 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 your credential's binding matches the active checkout and identity (see Security considerations): your checkout_id and identity must match the active checkout; network tokens must belong to your merchant_id.
4. Create payment - Map your Universal Commerce Protocol credential to a Worldline CreatePaymentRequest and call POST /v1/{merchantId}/payments. Your 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 your 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. Map Worldline errors to Universal Commerce Protocol errors (the Platform never sees Worldline error shapes).

Platform integration

Before using this handler, the Platform needs to:

1. Fetch the Business (You)'s Universal Commerce Protocol discovery profile (/.well-known/ucp).
2. Confirm com.worldline.globalcollect 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.globalcollect": [
      {
        "id": "worldline_globalcollect",
        "version": "2026-04-08",
        "spec": "https://ucp.connect.worldline-solutions.com/gc-payment-handler.md",
        "schema": "https://ucp.connect.worldline-solutions.com/2026-04-08/schema.json",
        "config": {}
      }
    ]
  }
}

Payment protocol

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

Step 1: Discover handler

Identify com.worldline.globalcollect 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 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 is 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_globalcollect",
        "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. Your 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_globalcollect_card):
  • Network token (preferred): Submit an externally provisioned network token via networkTokenData. Most transactions complete without requiring buyer authentication. The issuer may still request 3DS authentication when needed.
  • Raw card: Submit raw card.* card data for PCI-DSS-compliant server-to-server integrations only (for example, sandbox test cards). The issuer may trigger a 3DS challenge.
• Redirect (type: worldline_globalcollect_redirect): populate RedirectPaymentMethodSpecificInput for the chosen payment_product_id, including redirectionData.returnUrl and any product-specific input branch (iDEAL, PayPal, etc.).
• Mobile (type: worldline_globalcollect_mobile): obtain the encrypted wallet token from the wallet provider's API on the buyer's device and populate MobilePaymentMethodSpecificInput.

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

Step 4: Bind the credential

Include a binding object on your 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_globalcollect",
        "type": "card",
        "payment_product_id": 1,
        "selected": true,
        "credential": {
          "type": "worldline_globalcollect_card",
          "networkTokenData": { /* CardPaymentMethodSpecificInput fields */ },
          "binding": { "checkout_id": "chk_123", "identity": "buyer_abc" }
        }
      }
    ]
  }
}

Payment Service Provider integration (Global Collect)

Use these Worldline-specific details when implementing this handler.

• Server API base URLs. Sandbox: https://api.preprod.connect.worldline-solutions.com / Production: https://api.connect.worldline-solutions.com. Select the environment server-side through your config.environment.
• Payment products. payment_product_id values identify the Worldline product for each instrument type (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 your 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). You resolve these at create-checkout time via the Worldline Get Payment Product API (GET /v1/{merchantId}/products/{paymentProductId}) and surface them on the offered instrument's product_fields in the checkout response (see Platform Integration, Step 2). Discovery carries 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; you verify signatures with webhook_key_id / webhook_secret and reconcile them to Universal Commerce Protocol state.

Security considerations

References

• Handler Spec (this document): https://ucp.connect.worldline-solutions.com/gc-payment-handler.md
• Handler Schema (configuration, instrument, and credential shapes): https://ucp.connect.worldline-solutions.com/2026-04-08/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