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

| Participant | Integration Section |
| --- | --- |
| **Business (You)** | [Business integration](#business-integration) |
| **Platform** | [Platform integration](#platform-integration) |
| **Payment Service Provider (Global Collect)** | [Payment Service Provider integration (Global Collect)](#psp-integration-worldline-connect) |

* * *

Participants
------------

**Note on terminology:** Schema fields retain Worldline's industry nomenclature `merchant_*` (e.g., `merchant_id`). The Universal Commerce Protocol maps to the Worldline `merchant_id`, which is held server-side by you and never appears in the discovery profile. Mappings are documented below.

| Participant | Role | Requirement |
| --- | --- | --- |
| **Business (You)** | Holds Worldline credentials, advertises this handler in its Universal Commerce Protocol discovery profile, translates Universal Commerce Protocol calls into Worldline Connect Server API calls, verifies credential binding, and reconciles webhook events. Maps to Worldline `merchant_id` | Yes - a Worldline Connect account with products enabled. |
| **Platform** | The Universal Commerce Protocol agent or checkout surface. Discovers the handler through `/.well-known/ucp`, acquires the instrument (network token, raw card, redirect product, or wallet token), and submits it to you via Universal Commerce Protocol checkout-complete. | No - only needs to read the Business (You)'s discovery profile. |
| **Payment Service Provider (Global Collect)** | **Worldline GlobalCollect**. Authorizes and captures payments on behalf of the Business (You) and emits webhook events. | Yes - provides your account, products, and webhook configuration. |

Participant flow:

```
   Buyer
     | acquires credential (token / wallet / redirect)
     v
  Platform ----- Universal Commerce Protocol (discovery, checkout, complete) -----> Business (You)
                                                             | Worldline Connect Server API
                                                             v
                                                      Worldline Global Collect (Payment Service Provider)
                                                             | webhook events
                                                             v
                                                          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.

| Field | Description |
| --- | --- |
| `merchant_id` | Your Worldline merchant identifier. Held server-side; **not** present in the discovery profile. |
| `api_key_id` / `api_secret` | Your Worldline Connect Server API credentials. Held server-side. |
| `config.environment` | The only business configuration surfaced in discovery - sandbox or production. |

### Handler configuration

#### Handler Schema

**Schema URL:** [https://ucp.connect.worldline-solutions.com/2026-04-08/schema.json](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:

| Configuration variant | Used by | Purpose |
| --- | --- | --- |
| `business_schema` / `business_config` | Business discovery profile (`/.well-known/ucp`) | Surfaces the non-secret environment selector and the enabled products via `available_instruments`. |
| `platform_schema` / `platform_config` | Platform discovery profile | Empty - the platform configures nothing specific to Worldline Connect. |
| `response_schema` / `response_config` | Universal Commerce Protocol checkout/order responses | Empty - buyer handoff for redirect approval and card 3DS challenges uses the built-in Universal Commerce Protocol `requires_escalation` status + `continue_url`, not a handler-specific field. |

#### Business configuration fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (sandbox \| production) | No (default sandbox) | The Worldline Connect environment your handler targets. Your `merchant_id` and API credentials are deliberately not part of the discovery profile; they remain server-side with you. |

#### 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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| _(none)_ | - | - | When the buyer must approve a redirect product or complete a 3DS challenge, you set the checkout status to `requires_escalation`, place the Worldline approval/authentication URL in the standard top-level `continue_url`, and include a `messages` entry with severity `requires_buyer_input`. See the [Universal Commerce Protocol checkout status values](https://ucp.dev/2026-04-08/specification/checkout/#status-values). |

#### 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:

```json
{
  "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](#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)
5.  **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`.
6.  **Reconcile** - Resolve the final payment state via webhooks (preferred) or a `GET /payments/{paymentId}` fallback, then propagate to Universal Commerce Protocol checkout/order state.
7.  **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).

| Universal Commerce Protocol error | Worldline condition |
| --- | --- |
| DECLINED | `payment.status = REJECTED`, or a `merchantAction` with a declined response. |
| AUTHENTICATION_FAILED | 3DS challenge failed. |
| NETWORK_ERROR | HTTP 5xx or timeout, can be retried with `X-GCS-Idempotence-Key`. |
| INVALID_INSTRUMENT | HTTP 400 from Worldline - fix the request (do not retry). |

* * *

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.

| Field | Description |
| --- | --- |
| `available_instruments` | The static catalog of supported instrument types and products (with `brands` / `acquisition_modes` for card and `products` entries for redirect/mobile). |
| `config` | Conforms to `platform_config` - empty for this handler; no Worldline credentials are required on the Platform side. |

### Handler configuration

#### Platform configuration fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| _(none)_ | - | - | `platform_config` is empty. The Platform does not configure anything specific to Worldline Connect; Worldline credentials and policy live with the Business (You). |

#### Example platform handler declaration

```json
{
  "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).

```json
{
  "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:

```http
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
-----------------------

| Requirement | Description |
| --- | --- |
| **Binding required** | Credentials need to be bound to the Universal Commerce Protocol `checkout_id` and identity via the credential's `binding` object to prevent reuse. |
| **Binding placement** | Binding data is included **within** the credential payload (so it is covered by any signature over the credential), not in transport headers. |
| **Binding verified** | You verify the binding matches the active checkout before treating a credential as authoritative. Network tokens are additionally scoped to your `merchant_id`. |
| **Token expiry** | Network tokens and wallet tokens are single-use for a given checkout. |
| **Primary Account Number (PAN) handling** | Network tokens carry no Primary Account Number (PAN), and wallet tokens are encrypted by the wallet provider. Raw card data is used only in PCI-DSS-compliant server-to-server integrations and is never exposed to other participants. |
| **Data residency** | PII and card data are processed in the region tied to the Worldline merchant account; businesses with residency obligations need to confirm their account region. |
| **Transport** | Use TLS 1.2 or higher for all transport between participants. |

* * *

References
----------

*   **Handler Spec** (this document): [https://ucp.connect.worldline-solutions.com/gc-payment-handler.md](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](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/](https://ucp.dev/2026-04-08/specification/payment-handler-template/)
*   **Worldline Connect docs:** [https://docs.connect.worldline-solutions.com](https://docs.connect.worldline-solutions.com)