Payment Facilitator

📘

Your account must be enabled for this feature

This guide explains how a Payment Facilitator (PFAC) submits card transactions for a sub-merchant through the Payments REST API.

Integration models

The Gateway supports two onboarding models:

Prerequisites

Before sending a PFAC transaction, confirm with your integration support team that:

• the submitting store is boarded and enabled as a PFAC master store;
• the sub-merchant is eligible for the relevant acquiring route, card brands, transaction types, currencies, and countries;
• the required PFAC and sub-merchant identifiers have been agreed during onboarding;

Endpoint

POST {baseUrl}/payments

Use the base URL and authentication details supplied for your certification or production environment. Send the normal Payments REST API security headers, including a unique Client-Request-Id, and Content-Type: application/json.

Master-store sale request

Place paymentFacilitator inside paymentMethod, alongside paymentCard or the applicable supported card credential.

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "transactionOrigin": "ECOM",
  "merchantTransactionId": "PFAC-ORDER-20260828-0001",
  "order": {
    "orderId": "ORDER-20260828-0001"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "<card-number>",
      "securityCode": "<card-security-code>",
      "expiryDate": {
        "month": "08",
        "year": "29"
      }
    },
    "paymentFacilitator": {
      "subMerchantData": {
        "mcc": "5655",
        "legalName": "Example Sub-Merchant",
        "email": "[email protected]",
        "timezone": "Europe/Berlin",
        "address": {
          "address1": "Main Street 55",
          "address2": "Unit 234",
          "city": "Frankfurt",
          "region": "HE",
          "postalCode": "60311",
          "country": "DE"
        },
        "merchantId": "98765432",
        "merchantVerificationValue": "001122",
        "nationalTaxId": "DE123456789",
        "valueAddedTaxId": "DE123456789",
        "countryOfGovernmentalControl": "DE",
        "customerServicePhone": "+496912345678",
        "phone": "+496987654321",
        "url": "https://www.example.com"
      }
    }
  }
}

Request fields

Transaction fields

Sub-merchant fields

The API contract marks mcc as universally mandatory within subMerchantData. PFAC programs and acquiring routes commonly also require legalName, address, and merchantId, as shown below. Treat the onboarding profile for your route as authoritative when it requires additional fields.

Master-store PFAC fields

The following properties identify the Payment Facilitator rather than the sub-merchant:

• externalMerchantId
• paymentFacilitatorId
• saleOrganizationId
• name

For a configured master-store flow, the Gateway normally obtains these values from master data. Omit them unless your integration support team explicitly instructs you to submit them. Request values do not replace correct PFAC onboarding.

Downstream support is route-specific. “Mapped” means that the Gateway makes a value available to downstream routing; it does not guarantee that every processor or card scheme receives that value.

Transaction initiated from a sub-store

Use this model when each sub-merchant has been boarded as its own Gateway store. Authenticate for the sub-store, or supply its storeId if the authenticated application is authorized to submit transactions for multiple stores.

Do not include paymentFacilitator merely to identify the sub-store. The Gateway derives the PFAC relationship and applicable values from the boarded sub-store configuration.

{
  "storeId": "<boarded-sub-store-id>",
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "transactionOrigin": "ECOM",
  "merchantTransactionId": "SUBSTORE-ORDER-20260828-0001",
  "order": {
    "orderId": "ORDER-20260828-0001"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "<card-number>",
      "securityCode": "<card-security-code>",
      "expiryDate": {
        "month": "08",
        "year": "29"
      }
    }
  }
}

Omit storeId when the request credentials already identify the sub-store and the integration is not configured for multi-store submission. Do not put a PFAC-assigned sub-merchant identifier in storeId; it must be a Gateway store ID.

PFAC data for terminal transactions

The REST API also exposes PFAC data for card-present terminal request types:

• PaymentTerminalSaleTransaction
• PaymentTerminalPreAuthTransaction
• PaymentTerminalCreditTransaction

For these request types, paymentFacilitator is a top-level property of the transaction. It is not nested inside paymentMethod:

{
  "requestType": "PaymentTerminalSaleTransaction",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "transactionOrigin": "RETAIL",
  "storeId": "<pfac-master-store-id>",
  "terminalId": "<terminal-id>",
  "paymentMethod": {
    "paymentCard": {
      "number": "<terminal-captured-card-data>"
    }
  },
  "terminalRequestData": {
    "posEntryMode": "CONTACT_EMV",
    "offlineIndicator": false,
    "onlineReason": "ICC_FORCED",
    "emvData": "<terminal-emv-data>"
  },
  "pointOfSaleDevice": {
    "terminalProvider": "<provider>",
    "model": "<model>",
    "serialNumber": "<serial-number>"
  },
  "paymentFacilitator": {
    "subMerchantData": {
      "mcc": "5655",
      "legalName": "Example Sub-Merchant",
      "merchantId": "98765432",
      "address": {
        "address1": "Main Street 55",
        "city": "Frankfurt",
        "postalCode": "60311",
        "country": "DE"
      }
    }
  }
}

Terminal requests are card-present transactions and must use transactionOrigin: RETAIL. They also require the terminal-specific payment data, terminalId, terminalRequestData, and pointOfSaleDevice information defined for the certified terminal integration. The sample illustrates PFAC placement; the exact card or protected-card representation, EMV data, PIN data, device capabilities, and online/offline indicators must come from the certified terminal solution and must not be fabricated by a merchant application.

For a master-store terminal transaction, send the master-store storeId and the transaction's sub-merchant data in the top-level paymentFacilitator object.

Follow-up operations

For linked secondary transactions—VoidTransaction, ReturnTransaction (refund), and PostAuthTransaction—do not include subMerchantData.

The request is submitted to: POST {baseUrl}/payments/{ipgTransactionId} OR POST {baseUrl}/orders/{orderId}

The Gateway retrieves PFAC and sub-merchant data from the referenced primary transaction and carries it into the secondary transaction. The secondary request schema does not expose a paymentFacilitator property.

Important distinction: an unreferenced PaymentCardCreditTransaction is a new primary transaction, not a secondary refund. For a master-store PFAC credit, it may require paymentMethod.paymentFacilitator.subMerchantData.

This inheritance also applies when the original transaction was a PaymentTerminalSaleTransaction or PaymentTerminalPreAuthTransaction.