Create sub-merchant

Return to the list of PayFac API examples

Once you have established a Legal Entity, you can create one or more associated Sub-merchants. For example, if the Legal Entity controlled three different business at different locations, you would establish three Sub-merchants under the Legal Entity. You create new Sub-merchants by submitting a subMerchantCreateRequest message.

After the creation of a Sub-merchant, wait a minimum of two minutes before attempting to process transactions for the Sub-merchant. This is the minimum amount of time required for information about the newly created Sub-merchant to propagate through our system. Attempts to process transactions for a new Sub-merchant sooner than two minutes will result in system errors.

Resource Information

POST parameters

Example: Create Sub-merchant Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <subMerchantCreateRequest xmlns="http://psp.litle.com/api/merchant/onboard">
          <merchantName>Merchant Name</merchantName>
          <amexMid>1234567890</amexMid>
          <discoverConveyedMid>123456789012345</discoverConveyedMid>
          <url>http://merchantUrl</url>
          <customerServiceNumber>8407809000</customerServiceNumber>
          <hardCodedBillingDescriptor>billing Descriptor</hardCodedBillingDescriptor>
          <maxTransactionAmount>8400</maxTransactionAmount>
          <purchaseCurrency>USD</purchaseCurrency>
          <merchantCategoryCode>5964</merchantCategoryCode>
          <bankRoutingNumber>840123124</bankRoutingNumber>
          <bankAccountNumber>84012312415</bankAccountNumber>
          <pspMerchantId>123456</pspMerchantId>
          <fraud enabled="true"></fraud>
          <amexAcquired enabled="true"></amexAcquired>
          <address>
               <streetAddress1>Street Address 1</streetAddress1>
               <streetAddress2>Street Address 2</streetAddress2>
               <city>City</city>
               <stateProvince>MA</stateProvince>
               <postalCode>01970</postalCode>
               <countryCode>USA</countryCode>
          </address>
          <primaryContact>
               <firstName>John</firstName>
               <lastName>Doe</lastName>
               <phone>9785552222</phone>
               <emailAddress>John.Doe@company.com</emailAddress>
          </primaryContact>
          <createCredentials>true</createCredentials>
          <eCheck enabled="true">
               <eCheckCompanyName>Your Company Name</eCheckCompanyName>
               <eCheckBillingDescriptor>9785552222</eCheckBillingDescriptor>
          </eCheck>
          <subMerchantFunding enabled="false">
          <settlementCurrency>USD</settlementCurrency>
   </subMerchantCreateRequest>

Create Sub-Merchant Response

The response message to the Create Sub-merchant request has the following structure:

<subMerchantCreateResponse>
     <transactionId>0123456789</teansactionId>
     <subMerchantId>1</subMerchantId>
     <merchantIdentString>123456789</merchantIdentString>
     <originalSubMerchant> (included only in some dulpicate cases)
     <credentials> (included only if credentials requested)
     <paypageCredentials> (only if credentials requested and PayPage enabled)
     <amexSellerId>1234567890</amexSellerId>
</subMerchantCreateResponse>

If the submission is a duplicate with changed data, the submerchantId and merchantIdentString elements appear as children of the originalSubmerchant element.

Example: Create Sub-merchant Response with Credentials

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <subMerchantCreateResponse xmlns="http://psp.litle.com/api/merchant/onboard">
          <transactionId>82821240469914003</transactionId>
          <subMerchantId>1100003</subMerchantId>
          <merchantIdentString>01100003</merchantIdentString>
          <credentials>
               <userName>JDoe123</userName>
               <password>MyPassword</password>
               <passwordExpirationDate>2016-06-30T23:59:59-05:00</passwordExpirationDate>
          </credentials>
          <paypageCredentials>
               <paypagCredential>
                    <userName>JDoe123</userName>
                    <paypageId>1234567890123456</paypageId>
               </paypagCredential>
          </paypageCredentials>
          <amexSellerId>1234567890</amexSellerId>
     </subMerchantCreateResponse>

Example: Create Sub-merchant Response - Duplicate with All Data Matching

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <subMerchantCreateResponse xmlns="http://psp.litle.com/api/merchant/onboard" duplicate="true">
          <transactionId>82821240469914003</transactionId>
          <subMerchantId>1100003</subMerchantId>
          <merchantIdentString>01100003</merchantIdentString>
     </subMerchantCreateResponse>

Example: Create Sub-merchant Response - Duplicate with Data Not Matching

<subMerchantCreateResponse xmlns="http://psp.litle.com/api/merchant/onboard" duplicate="true">
     <transactionId>82821240469914003</transactionId>
     <originalSubMerchant>
          <merchantName>Merchant Name</merchantName>
          <amexMid>1234567890</amexMid>
          <discoverConveyedMid>123456789012345</discoverConveyedMid>
          <url>http://merchantUrl</url>
          <customerServiceNumber>8407809000</customerServiceNumber>
          <hardCodedBillingDescriptor>billing Descriptor</hardCodedBillingDescriptor>
          <maxTransactionAmount>8400</maxTransactionAmount>
          <purchaseCurrency>USD</purchaseCurrency>
          <merchantCategoryCode>5964</merchantCategoryCode>
          <bankRoutingNumber>840123124</bankRoutingNumber>
          <bankAccountNumber>84012312415</bankAccountNumber>
          <pspMerchantId>123456</pspMerchantId>
          <address>
               <streetAddress1>Street Address 1</streetAddress1>
               <streetAddress2>Street Address 2</streetAddress2>
               <city>City</city>
               <stateProvince>MA</stateProvince>
               <postalCode>01970</postalCode>
               <countryCode>USA</countryCode>
          </address>
          <primaryContact>
               <firstName>John</firstName>
               <lastName>Doe</lastName>
               <phone>9785552222</phone>
               <emailAddress>John.Doe@company.com</emailAddress>
          </primaryContact>
          <subMerchantId>1002</subMerchantId>
          <merchantIdentString>01100002</merchantIdentString>
     </originalSubMerchant>
</subMerchantCreateResponse>

See Status Codes and Error Messages

Next: Update sub-merchant

Return to the list of PayFac API Examples