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
HTTP method | POST |
Call | /legalentity/legalEntityId/submerchant |
Request format | XML |
Response format | XML |
Rate limited | Yes |
POST parameters
Parameter | Required or Optional | Description |
legalEntityId | Required | The Id of the Legal Entity |
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