🚧

In development

A legacy version of the Merchant Boarding API is live currently, however a new enhanced version is in development. For new consumers, it is highly recommended to use the new version of the API expected in Q3 2022.

Please note the API specification may change while it's in development

Stores Resource

Stores are the physical or online store where transaction take place. Information about the type of aquiring offer and terminal equipment is captured here. It's vital to get this information correct as it is used to start the process of underwriting, ordering/shipping of equipment, risk management and more.

Mandatory Fields

AttributeTypeDescriptionExample / ENUMS
annualCardTurnoverstringThe combined annual card sales for the store90000
annualTurnoverstringThe overall business turnover (cards and cash) for the store120000
currencyCodestringThe store currency codeGBP (3 byte alpha ISO code)
estimateAverageTicketstringThe estimated average transaction value for the store100
mccstringThe Merchant Category Code for the store1711 - Full list of MCC codes
prodServSoldstringA description of goods and services sold for the storeshoes
tradeNamestringThe trade name of the storeJohn Smith Shoe Shop
accountTypestringDefines the type of bank account that the information is being sent/stored for (e.g. Payment Account retail, Merchant Hold account, etc.)Payment Account Retail

Conditional Fields

The majority of these conditional parameters are required when Fiserv's specific underwriting systems (Dilligence, RMW...) are used to assess merchants after the orders are submitted for processing.
The first two attributes below are not specific to underwriting.

AttributeTypeDescriptionExample / ENUMSCondition
clientRegionSysIdstringThe ID for the chosen client region used for settlement for Fiserv clients using the OmniPay Acquiring platform. This code is assigned by Fiserv and must be obtained before integration into the boarding API.345Mandatory in case the Fiserv's Omnipay Acquiring Platform will be used for the transaction processing of the merchants.
storeWebsitestringThe website address for the store. Mandatory if salesInternetPerc is greater than 0https://www.johnsmithshoes.comMandatory if the store is an e-commerce shop.
businessTypestringThe high level business type (hotel, retail, etc) for the storeretailMandatory in case Fiserv's RMW tools will be used for transaction risk monitoring
delivery0DaysPercstringThe overall % for a business of product delivery within 0 days (same day) for the store. Total of all delivery days fields must equal 10020Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
delivery1To7DaysPercstringThe overall % for a business of product delivery within 1 to 7 days for the store. Total of all delivery days fields must equal 10020Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
delivery8To14DaysPercstringThe overall % for a business of product delivery within 8 to 14 days for the store. Total of all delivery days fields must equal 10020Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
delivery15To30DaysPercstringThe overall % for a business of product delivery within 15 to 30 days for the store. Total of all delivery days fields must equal 10020Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
deliveryOver30DaysPercstringThe overall % for a business of product delivery over 30 days for the store. Total of all delivery days fields must equal 10020Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
salesFtfPercstringThe % of card present/face to face sales for the store. Total of all sales percentage fields must equal 10050Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
salesInternetPercstringThe % of ecom/internet sales for the store. Total of all sales percentage fields must equal 10025Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchatns
salesMotoPercstringThe % of mail/telephone order sales for the store. Total of all sales percentage fields must equal 10025Mandatory if Fiserv's Dilligence system will be used to perform the credit risk assessments of the merchants
externalMerchantIdstringTo be used when a merchant ID (MID) is allocated by the Alliance/Partner to the trading entity/store and the Fiserv MID allocation service is not used in such case555873973614Mandatory if the merchant id has been pre allocated by the client
accountTypeSysIdstringSystem ID used to identify the bank account type for Fiserv clients using the OmniPay acquiring platform196

Optional Fields

The following optional parameters are required mainly in cases when credit risk assessment is to be performed by Fiserv after the order is submitted.

AttributeTypeDescriptionExample / ENUMS
clientRegionstringThe name of the client region to be used for settlement for Fiserv clients using the OmniPay Acquiring platformBy Transaction
recurringFlagbooleanFlag to show if recurring payments are taken by the customer for the storefalse; true

Selected Offers

If you are not familiar with retrieving a list of available offers, please refer to the Offers Management System guide.

Acquiring Offer

The acquiring offer entity contains important information related to the transaction and service products and pricing for a particular store. It is not mandatory to send an acquiring offer, but if one is sent then all three attributes below are mandatory.

AttributeTypeDescriptionExample / Enums
acquiringOfferingExternalIdstringThe unique ID allocated to the acquiring offer that is returned in the API response from the Offer Management SystemACOD1-8FE34-CE11F-FEA73-2CA47-DB04F-C93FD
postingTariffIdstringThe ID for the posting tariff configured in the acquiring offering for Fiserv clients using the OmniPay Acquiring platform returned in the API response from the Offer Management System678
settlementMethodIdstringThe ID for the settlement tariff configured in the acquiring offering for Fiserv clients using the OmniPay Acquiring platform returned in the API response from the Offer Management System445

Transaction Charges

The transaction charges entity contains important information related to the transaction item/card based products and pricing that have been selected for a customer from the available options in the acquiring offer.

It is not mandatory to send transaction charges, but if they are sent they must be linked with an acquiring offer, the transactionChargeItemExternalId must be sent, and one of feeBase or feePercentage must also be sent.

AttributeTypeDescriptionExample / Enums
transactionChargeItemExternalIdUUIDThe unique ID allocated to the transaction item (Visa Debit, etc.) that is returned in the API response from the Offer Management SystemTCIB4-EAA05-E466A-ED065-205F8-6EC63-16430
feeBasestringThe base/monetary rate that the customer will be charged for this transaction item. Either of feePercentage or feeBase must be provided. Both CAN be provided1.5
feePercentagestringThe percentage rate that the customer will be charged for this transaction item. Either of feePercentage or feeBase must be provided. Both CAN be provided10
feeMinstringThe minimum fee amount that will be charged for this transaction item. Optional setting for Fiserv clients using the OmniPay Acquiring platform2
feeMaxstringThe maximum fee amount that will be charged for this transaction item. Optional setting for Fiserv clients using the OmniPay Acquiring platform10

Service Charges

AttributeTypeDescriptionExample / Enums
serviceChargeItemExternalIdUUIDThe unique ID allocated to the service item (chargeback fee, joining fee, etc.) that is returned in the API response from the Offer Management SystemSCIBD-C7BEE-A94E4-F66DE-9B822-FDB3C-56D9E
feeBasestringThe base/monetary rate that the customer will be charged for this service item. Either a feePercentage or feeBase must be provided. Both CAN be provided1.5
feePercentagestringThe percentage rate that the customer will be charged for this service item. Either a feePercentage or feeBase must be provided. Both CAN be provided1
feeMinstringThe minimum fee amount that will be charged for this Service Charge item. Optional setting for Fiserv clients using the OmniPay Acquiring platform2
feeMaxstringThe maximum fee amount that will be charged for this Service Charge item. Optional setting for Fiserv clients using the OmniPay Acquiring platform10

Equipment offers

Equipment offering ID

AttributeTypeDescriptionExample / Enums
equipmentOfferingExternalIdstringThe unique ID allocated to the equipment offer that is returned in the API response from the Offer Management SystemEQOC1-A884F-B6FC6-E3BDD-828F3-CA737-1AAF0

equipmentsBundle

AttributeTypeDescriptionExample / Enums
equipmentBundleExternalIdstringThe unique ID allocated to the equipment bundle that is returned in the API response from the Offer Management SystemEQB06-7C4BA-280A7-B35C6-486AF-2AE45-E707F
bundleItems
AttributeTypeDescriptionExample / Enums
equipmentExternalIdstringThe unique ID allocated to the equipment/service (Clover Flex, PCI, etc.) that is returned in the API response from the Offer Management SystemPRO7B-F61FC-12319-7B003-F3E4C-2B10E-ADA2F
billingMethodExternalIdstringThe unique ID allocated to the billing method (Purchase, 12 Month Rental, etc) that is returned in the API response from the Offer Management System.PBM6B-60B34-ECCA5-83DD2-F75A4-1942A-A0F41
quantityintegerNumber of equipment with the same bundle set up1
AttributeTypeDescriptionExample / Enums
externalTerminalIdstringThe uniquie ID allocated to the terminal. This can be allocated during the terminal activation process by Fiserv or by the customerDE123456
terminalActivationDatedateThe date when the terminal has been activated. If date is null then terminal is awaiting activation. If date is set to 9999/12/31 then activation has been cancelled or failed2020-05-26
terminalPricestringThe amount that the customer will be charged for the purchase/rental of equipment.19.99

features

The features contains important information related to the additional facilities/paramaters associated to a particular equipment/service

AttributeTypeDescriptionExample / Enums
featureExternalIdstringThe unique ID allocated to the feature (Cashback, Moto, etc) that is returned in the API response from the Offer Management SystemPRF2B-43A76-7D01B-3096A-D86CE-5F2CF-661F1
valuebooleanThe required value to be set against a feature that is associated to an equipment/serviceY

Examples

Example Request

{
     "acquiringOffer": {
          "acquiringOfferingExternalId": "ACOC1-A884F-B6FC6-E3BDD-828F3-CA737-1AAF0",
          "postingTariffId": "678",
          "settlementMethodId": "445",
          "serviceCharges": [
               {
                    "serviceChargeItemExternalId": "EQ146-12368-91852-66F6E-AEA69-40D7D-6C845",
                    "feeBase": "0.35",
                    "feePercentage": "30",
                    "feeMin": "1",
                    "feeMax": "40"
               }
          ],
          "transactionCharges": [
               {
                    "transactionChargeItemExternalId": "EQ146-12368-91852-66F6E-AEA69-40D7D-6C846",
                    "feeBase": "0.35",
                    "feePercentage": "30",
                    "feeMin": "1",
                    "feeMax": "40"
               }
          ]
     },
     "equipmentOffer": {
          "equipmentOfferingExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
          "equipmentBundles": [
               {
                    "equipmentBundleExternalId": "HQOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
                    "bundleItems": [
                         {
                              "equipmentBundleItemExternalId": "EBI0C-0355A-A3226-723D2-BF472-49CA1-B8D9D",
                              "billingMethodExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EB",
                              "equipmentExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EC",
                              "externalTerminalId": "DE123456",
                              "terminalPrice": "50.99",
                              "quantity": 1,
                              "terminalActivationDate": "2022-04-07",
                              "features": [
                                   {
                                        "featureExternalId": "APOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
                                        "value": "Y"
                                   }
                              ],
                              "terminalLinking": {
                                   "linkedServices": [
                                        {
                                             "id": "PQOB9-E635E-79776-8D286-A1090-7E0E1-B37B1"
                                        }
                                   ],
                                   "linkedEquipment": [
                                        {
                                             "id": "PROB9-D635E-69776-9D286-A1090-9E0E1-A37B1"
                                        }
                                   ]
                              }
                         }
                    ]
               }
          ]
     },
     "bankAccounts": [
          {
               "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
               "accountType": "Payment Account Retail",
               "accountTypeSystemId": "196",
               "dateFrom": "2022-04-07",
               "dateTo": "2022-04-07"
          }
     ],
     "contacts": [
          {
               "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
     ],
     "tradeName": "John Smith Shoe Shop",
     "mcc": "0742",
     "storeWebsite": "https://store-webpage-test.com",
     "currencyCode": "GBP",
     "clientRegion": "900",
     "clientRegionSystemId": "345",
     "annualTurnover": "64000",
     "annualCardTurnover": "56000",
     "delivery0DaysPerc": "100",
     "delivery1To7DaysPerc": "0",
     "delivery8To14DaysPerc": "0",
     "delivery15To30DaysPerc": "0",
     "deliveryOver30DaysPerc": "0",
     "estimateAverageTicket": "1000",
     "prodServSold": "Shoe repair",
     "recurringPaymentsFlag": true,
     "salesFtfPerc": "62",
     "salesInternetPerc": "30",
     "salesMotoPerc": "8",
     "externalMerchantId": "520334547514337",
     "businessType": "Retail",
     "storeType": "PHYSICAL"
}

Example Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "acquiringOffer": {
    "acquiringOfferingExternalId": "ACOC1-A884F-B6FC6-E3BDD-828F3-CA737-1AAF0",
    "postingTariffId": "678",
    "settlementMethodId": "445",
    "serviceCharges": [
      {
        "serviceChargeItemExternalId": "EQ146-12368-91852-66F6E-AEA69-40D7D-6C845",
        "feeBase": "0.35",
        "feePercentage": "30",
        "feeMin": "1",
        "feeMax": "40"
      }
    ],
    "transactionCharges": [
      {
        "transactionChargeItemExternalId": "EQ146-12368-91852-66F6E-AEA69-40D7D-6C846",
        "feeBase": "0.35",
        "feePercentage": "30",
        "feeMin": "1",
        "feeMax": "40"
      }
    ]
  },
  "equipmentOffer": {
    "equipmentOfferingExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
    "equipmentBundles": [
      {
        "equipmentBundleExternalId": "HQOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
        "bundleItems": [
          {
            "equipmentBundleItemExternalId": "EBI0C-0355A-A3226-723D2-BF472-49CA1-B8D9D",
            "billingMethodExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EB",
            "equipmentExternalId": "EQOE4-7F631-E36B4-D2ACF-2F432-79769-162EC",
            "externalTerminalId": "DE123456",
            "terminalPrice": "50.99",
            "quantity": 1,
            "terminalActivationDate": "2022-04-07",
            "features": [
              {
                "featureExternalId": "APOE4-7F631-E36B4-D2ACF-2F432-79769-162EA",
                "value": "Y"
              }
            ],
            "terminalLinking": {
              "linkedServices": [
                {
                  "id": "PQOB9-E635E-79776-8D286-A1090-7E0E1-B37B1"
                }
              ],
              "linkedEquipment": [
                {
                  "id": "PROB9-D635E-69776-9D286-A1090-9E0E1-A37B1"
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "bankAccounts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "accountType": "Payment Account Retail",
      "accountTypeSystemId": "196",
      "dateFrom": "2022-04-07",
      "dateTo": "2022-04-07"
    }
  ],
  "contacts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "tradeName": "John Smith Shoe Shop",
  "mcc": "0742",
  "storeWebsite": "https://store-webpage-test.com",
  "currencyCode": "GBP",
  "clientRegion": "900",
  "clientRegionSystemId": "345",
  "annualTurnover": "64000",
  "annualCardTurnover": "56000",
  "delivery0DaysPerc": "100",
  "delivery1To7DaysPerc": "0",
  "delivery8To14DaysPerc": "0",
  "delivery15To30DaysPerc": "0",
  "deliveryOver30DaysPerc": "0",
  "estimateAverageTicket": "1000",
  "prodServSold": "Shoe repair",
  "recurringPaymentsFlag": true,
  "salesFtfPerc": "62",
  "salesInternetPerc": "30",
  "salesMotoPerc": "8",
  "externalMerchantId": "520334547514337",
  "businessType": "Retail",
  "storeType": "PHYSICAL"
}

Bulk stores Resource

In some instances you might want to create multiple stores early on in the boarding journey. Using the bulk stores resource you can generate IDs for multiple stores in one request. Simply send the number of physical stores and/or the number of online stores in the request, and receive back the individual IDs for each store. These stores will then beed to be completed using the stores PATCH endpoints described above.

Examples

Example Request

{
  "numberOfPhysicalStores": 1,
  "numberOfOnlineStores": 2
}

Example Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "stores": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "PHYSICAL"
    }
  ]
}

Did this page help you?