Payment Facilitator

📘

Your account has to be enabled for this feature

Use this feature when you act as a payment facilitator (PFAC) and submit nexo transactions for sub-merchants through a single PFAC master store. In this model, each sub-merchant does not require a separate Gateway store, but every PFAC transaction must identify both the master store used for routing and the sub-merchant on whose behalf the transaction is submitted.

Identifier model

The master-store ID, terminal ID, and sub-merchant ID are different identifiers and must not be interchanged.

Do not place PFAC sub-merchant data in Cntxt/SaleCntxt/SpnsrdMrchnts. For the master-store PFAC model described here, the Gateway takes the sub-merchant identity and address from Envt/Mrchnt and the MCC from Tx/MrchntCtgyCd.

Required PFAC request data

The following fields are mandatory when a transaction is intended to be processed through the PFAC master-store model. Standard mandatory fields for the selected nexo message remain required and are not repeated in this table.

m means mandatory for a transaction submitted through this PFAC master-store model.

XML element order

nexo XML is sequence-sensitive. Within PstlAdr, place the elements in schema order.

StrtNm
BldgNb
PstCd
TwnNm
Ctry

Example

The following fragment shows the placement of the PFAC-specific values in an Acceptor Authorisation Request. It is not a complete transaction request; standard header, card, context, transaction-detail, and security fields are abbreviated.

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:caaa.001.001.06">
  <AccptrAuthstnReq>
    <Hdr>
      <!-- Standard nexo header fields -->
    </Hdr>
    <AuthstnReq>
      <Envt>
        <!-- Standard acquirer data, where applicable -->
        <Mrchnt>
          <Id>
            <Id>SUBMERCHANT-000123</Id>
          </Id>
          <CmonNm>Example Shop Berlin</CmonNm>
          <LctnAndCtct>
            <PstlAdr>
              <StrtNm>Friedrichstrasse</StrtNm>
              <BldgNb>100</BldgNb>
              <PstCd>10117</PstCd>
              <TwnNm>Berlin</TwnNm>
              <Ctry>DE</Ctry>
            </PstlAdr>
          </LctnAndCtct>
        </Mrchnt>
        <POI>
          <Id>
            <Id>TERM-0001</Id>
          </Id>
          <GrpId>PFAC-MASTER-STORE-001</GrpId>
          <!-- Standard POI capabilities and components -->
        </POI>
        <!-- Standard card and cardholder data -->
      </Envt>
      <Cntxt>
        <!-- Standard payment and sale context -->
      </Cntxt>
      <Tx>
        <TxCaptr>true</TxCaptr>
        <TxTp>CRDP</TxTp>
        <MrchntCtgyCd>5411</MrchntCtgyCd>
        <!-- Standard transaction identifiers and amount data -->
      </Tx>
    </AuthstnReq>
    <!-- Security trailer when required by the certified setup -->
  </AccptrAuthstnReq>
</Document>

How the Gateway interprets the request

For a correctly configured PFAC master store, the Gateway interprets the request as follows:

1. Envt/POI/GrpId selects the PFAC master store.
2. Envt/Mrchnt/Id/Id becomes the sub-merchant identifier.
3. Envt/Mrchnt/CmonNm becomes the sub-merchant name used for PFAC processing.
4. Tx/MrchntCtgyCd becomes the sub-merchant MCC.
5. The supported postal-address fields become the sub-merchant address.
6. The Gateway obtains the configured PFAC identifiers, Sales Organization ID, PFAC name or descriptor prefix, and other route-specific PFAC values from the master-store configuration.

The presence of Envt/Mrchnt alone does not activate PFAC processing. The request must resolve to a store that has been configured for the PFAC master-store model.

If PFAC sub-merchant data is omitted, do not assume the Gateway will reject the transaction. Depending on the configured flow, the transaction can be handled as a normal non-PFAC transaction. Always verify PFAC attribution during certification.

Merchant name and descriptor handling

Envt/Mrchnt/CmonNm supplies the dynamic sub-merchant name. It should contain the trading or display name agreed with Fiserv rather than an arbitrary internal label.

The final merchant name or descriptor sent downstream can combine a configured PFAC name or prefix with the sub-merchant name. The separator, permitted characters, and maximum transmitted length can vary by processor, card brand, and region. The Gateway may convert unsupported characters and truncate values to downstream field lengths.

Confirm the final value in authorization testing, clearing or settlement output, receipts, and cardholder-facing statements where applicable.

Unsupported sub-merchant fields

The following values are not part of the supported nexo PFAC sub-merchant mapping described on this page. Do not rely on them being forwarded downstream:

• merchant telephone number;
• customer-service telephone number;
• email address;
• URL;
• a separate second address line; and
• state, province, or country subdivision.

If one of these values is required by an acquiring route or card scheme, confirm the supported integration approach with your relationship manager before implementation.

Transaction lifecycle

Include the PFAC data on every primary financial request submitted through the master store for a sub-merchant.

For completions, refunds, voids, reversals, and other transactions linked to an earlier payment:

• use the standard nexo message type and original-transaction identifiers for that operation;
• do not use a secondary request to change the sub-merchant attribution of the original transaction; and
• include the same PFAC related data into secondary transactions

Response handling

The Gateway returns the standard nexo response for the selected transaction type. There is no separate PFAC response object that proves how the transaction was represented to the downstream processor.

A successful nexo response confirms Gateway processing only. It does not by itself confirm the final descriptor, clearing record, settlement attribution, or card-scheme acceptance. Validate those outputs during end-to-end certification.