Guides

Creating a merchant

Suggest Edits

Quick example for creating a merchant

The example below demonstrates how to create the simplest possible merchant that can process ACH transactions using entry class WEB. 

Client client = new Client();
client.SetBasicAuth("[email protected]", "notArealpassw0rd");

Merchant m = new Merchant()
{
  ClientName = "Test Merchant",
  ContactEmail = "[email protected]",
  ReceivingRoutingNumber = "123456780",
  BillingDDANumber = "123456780",
  BillingRoutingNumber = "123456780",
  ReceivingDDANumber = "123123123",
  OdfiAccount = "9600000606",
  IsActive = true,
  ValidEntryClassCodes = new ObservableCollection<EntryClass> { EntryClass.WEB}
};
var result = client.CreateMerchantAsync(m).Result;

ApiClient defaultClient = Configuration.getDefaultApiClient();
        
HttpBasicAuth auth = (HttpBasicAuth)defaultClient.getAuthentication("basicAuth");
auth.setUsername("[email protected]);
auth.setPassword("notArealpassw0rd");

MerchantsApi apiInstance = new MerchantsApi();
Merchant merchant = new Merchant();

ArrayList<Merchant.ValidEntryClassCodesEnum> validECCs = new ArrayList<Merchant.ValidEntryClassCodesEnum>();
        validECCs.add(Merchant.ValidEntryClassCodesEnum.WEB);

merchant.setClientName("Test Merchant Java");
merchant.setContactEmail("[email protected]");
merchant.setReceivingRoutingNumber("123456780");
merchant.setBillingDDANumber("123456780");
merchant.setBillingRoutingNumber("123456780");
merchant.setReceivingDDANumber("123123123");
merchant.setOdfiAccount("9600000301");
merchant.setIsActive(true);
merchant.setValidEntryClassCodes(validECCs);

Merchant createdMerchant = apiInstance.createMerchant(merchant);

[[ACHConfiguration sharedConfig] username] = @"[email protected]";
[[ACHConfiguration sharedConfig] password] = @"notArealpassword";

ACHMerchantsApi *apiInstance = [[ACHMerchantsApi alloc] init];
ACHMerchant *merchant = [[ACHMerchant alloc] init];


[merchant setClientName:@"Test Merchant Objc"];
[merchant setContactEmail:@"[email protected]"];
[merchant setReceivingRoutingNumber:@"123456780"];
[merchant setReceivingDDANumber:@"123456780"];
[merchant setBillingRoutingNumber:@"123456780"];
[merchant setBillingDDANumber:@"123456780"];
[merchant setIsActive:@1];
[merchant setOdfiAccount:@"9600000301"];
[merchant setValidEntryClassCodes:@[@"WEB"]];



[apiInstance createMerchantWithMerchant:merchant
 completionHandler:^(ACHMerchant *output, NSError *error) {
   if (output) {
     NSLog(@"%@", output);
   } 
   if (error) {
     NSLog(@"Error calling ACHMerchantsApi->createMerchantWithMerchant: %@", error);
   }
 }];

Setting creation options

When creating a merchant the first thing to do is initialize an object with the necessary fields set. The code sample below initializes an object for creating a merchant. All possible options are displayed and documented below. The code is only shown for C#. The semantics change only slightly for Objective-C and Java.

Merchant m = new Merchant()
{
  // Merchant Info
  ClientName = "Test Merchant",
  ContactEmail = "[email protected]",
  ReceivingRoutingNumber = "123456780",
  BillingDDANumber = "123456780",
  BillingRoutingNumber = "123456780",
  ReceivingDDANumber = "123123123",
  OdfiAccount = "9600000606",
  IsChecking = true,
  ReportsTo = "9900000778",
  
  // Merchant Settings
  IsActive = true,
  IsDemoAccount = false,
  AutoBatchApproval = true,
  CanUpload = true,
  AllowDuplicateItems = false,
  AllowEditAmount = false,
  HighRisk = false,
  RoutingModel = RoutingModel.ACHWithC21,
  DefaultECC = EntryClass.ARC,
  
  // File Specific Details
  AchCompanyName = "Test Merchant",
  DiscretionaryData = "",
  NoOffsetFunding = false,
  ContactPerson = "A.D. Ministrator",
  ContactPhone = "555-555-5555",
  
  // Transaction Type Management
  ValidEntryClassCodes = new ObservableCollection<EntryClass>() { EntryClass.WEB},
  TerminalCity = "",
  TerminalState = "AL",
  
  // Transaction Limits
  DailyFileLimit = 0,
  DailyLimit = 0,
  DailySoftLimit = 0,
  MonthlyFileLimit = 0,
  MonthlyLimit = 0,
  MonthlySoftLimit = 0,
  TransactionLimit = 0,
  TransactionSoftLimit = 0,
  IsSuspectEnabled = false,
  
  //Clearing Account
  UseClearingAccount = false,
  ReserveBalance = 0,
  ReserveRequirement = 0,
  ReserveFundlingLevel = 0,
  DisburseReleaseDays = 0,
  HoldFunds = false,
  AggregateDisbursements = false,

  //Returned Item Handling
  AutoRejectHandling = false,
  RecoveryAccountId = null,
  RejectHoldingDays = 0,

  //Verificaiton
  RequirePreAuth = false,
  RvdRuleSet = "",
  SecurityKey = "",
  UseSPS = false
};

Merchant m = new Merchant();

// Merchant Info
m.setClientName("Test Merchant");
m.setContactEmail("[email protected]");
m.setReceivingRoutingNumber("123456780");
m.setBillingDDANumber("123456780");
m.setBillingRoutingNumber("123456780");
m.setReceivingDDANumber("123123123");
m.setOdfiAccount("9600000606");
m.setIsChecking(true);
m.setReportsTo("9900000778");

// Merchant Settings
m.setIsActive(true);
m.setIsDemoAccount(false);
m.setAutoBatchApproval(true);
m.setCanUpload(true);
m.setAllowDuplicateItems(false);
m.setAllowEditAmount(false);
m.setHighRisk(false);
m.setRoutingModel(RoutingModel.ACHWITHC21);
m.setDefaultECC(EntryClass.ARC);

// File Specific Details
m.setAchCompanyName("Test Merchant");
m.setDiscretionaryData("");
m.setNoOffsetFunding(false);
m.setContactPerson("A.D. Ministrator");
m.setContactPhone("555-555-5555");

// Transaction Type Management
ArrayList<Merchant.ValidEntryClassCodesEnum> validECCs = new ArrayList<Merchant.ValidEntryClassCodesEnum>();
validECCs.add(Merchant.ValidEntryClassCodesEnum.WEB);
m.setValidEntryClassCodes(validECCs);
m.setTerminalCity("");
m.setTerminalState("AL");

// Transaction Limits
m.setDailyFileLimit(0);
m.setDailyLimit(BigDecimal.ZERO);
m.setDailySoftLimit(BigDecimal.ZERO);
m.setMonthlyFileLimit(0);
m.setMonthlyLimit(BigDecimal.ZERO);
m.setMonthlySoftLimit(BigDecimal.ZERO);
m.setTransactionLimit(BigDecimal.ZERO);
m.setTransactionSoftLimit(BigDecimal.ZERO);
m.setIsSuspectEnabled(false);

//Clearing Account
m.setUseClearingAccount(false);
m.setReserveBalance(BigDecimal.ZERO);
m.setReserveRequirement(BigDecimal.ZERO);
m.setReserveFundlingLevel(0);
m.setDisburseReleaseDays(0);
m.setHoldFunds(false);
m.setAggregateDisbursements(false);

//Returned Item Handling
m.setAutoRejectHandling(false);
m.setRecoveryAccountId(null);
m.setRejectHoldingDays(0);

//Verificaiton
m.setRequirePreAuth(false);
m.setRvdRuleSet("");
m.setSecurityKey("");
m.setUseSPS(false);

ACHMerchant *m = [[ACHMerchant alloc] init];
    
// Merchant Info
[m setClientName:@"Test Merchant"];
[m setContactEmail:@"[email protected]"];
[m setReceivingRoutingNumber:@"123456780"];
[m setBillingDDANumber:@"123456780"];
[m setBillingRoutingNumber:@"123456780"];
[m setReceivingDDANumber:@"123123123"];
[m setOdfiAccount:@"9600000606"];
[m setIsChecking:@1];
[m setReportsTo:@"9900000778"];

// Merchant Settings
[m setIsActive:@0];
[m setIsDemoAccount:@0];
[m setAutoBatchApproval:@1];
[m setCanUpload:@1];
[m setAllowDuplicateItems:@0];
[m setAllowEditAmount:@0];
[m setHighRisk:@0];
[m setRoutingModel:@"ACHWithC21"];
[m setDefaultECC:@"ARC"];

// File Specific Details
[m setAchCompanyName:@"Test Merchant"];
[m setDiscretionaryData:@""];
[m setNoOffsetFunding:@0];
[m setContactPerson:@"A.D. Ministrator"];
[m setContactPhone:@"555-555-5555"];

// Transaction Type Management
[m setValidEntryClassCodes:@[@"WEB",@"TEL"]];
[m setTerminalCity:@""];
[m setTerminalState:@"AL"];

// Transaction Limits
[m setDailyFileLimit:@0];
[m setDailyLimit:@0];
[m setDailySoftLimit:@0];
[m setMonthlyFileLimit:@0];
[m setMonthlyLimit:@0];
[m setMonthlySoftLimit:@0];
[m setTransactionLimit:@0];
[m setTransactionSoftLimit:@0];
[m setIsSuspectEnabled:@0];

//Clearing Account
[m setUseClearingAccount:@0];
[m setReserveBalance:@0];
[m setReserveRequirement:@0];
[m setReserveFundlingLevel:@0];
[m setDisburseReleaseDays:@0];
[m setHoldFunds:@0];
[m setAggregateDisbursements:@0];

//Returned Item Handling
[m setAutoRejectHandling:@0];
[m setRecoveryAccountId:nil];
[m setRejectHoldingDays:@0];

//Verificaiton
[m setRequirePreAuth:@0];
[m setRvdRuleSet:@""];
[m setSecurityKey:@""];
[m setUseSPS:@0];

You normally wouldn't use every single field. In fact, you will probably not need to use most fields.

Merchant Information

  • ClientName (required) - This is the name the merchant will appear as in the UI.
  • ContactEmail (required) - Contact email of merchant
  • ReceivingRoutingNumber (required) - Routing number of the account where disbursements will be sent.
  • ReceivingDDANumber (required) - Bank account number of the account where disbursements will be sent.
  • BillingRoutingNumber (required) - Routing number of the account where bills will be debited from. Note that this is an optional feature but a required field.
  • BillingDDANumber (required) - Account number of the account where bills will be debited from. Note that this is an optional feature but a required field.
  • OdfiAccount (required) - This is the ID of the clearing account registered in the ACHeck21 system. This will be set up ahead of time and you will have received this id.
  • IsChecking - Should be true if the receiving account is a checking account, false if the receiving account is a savings account.
  • ReportsTo - The parent of this merchant. Merchants are organized hierarchically with an infinite number of possible levels. This means an individual merchant account can represent an entire organization, a division within an organization, or a single location.

Merchant Settings

  • IsActive - If true, this merchant can process transactions.
  • IsDemoAccount - If true, this merchant can process transactions but no money will actually be sent or received. Note that this also requires an appropriate "demo" ODFI.
  • AutoBatchApproval - If true, all batches for this merchant will not require approval before processing. If false, batches from this merchant won't be processed until they are approved by someone in the gateway..
  • CanUpload - If true, allows the merchant to upload batch files.
  • AllowDuplicateItems - If true, allows items with the same routing, account, and check number to be processed more than once. Recommended to be false.
  • AllowEditAmount - If true, allows check21 transaction amounts to be manually corrected before processing. Does not apply to ACH transactions.
  • HighRisk - Can be used to indicate a merchant is high risk. This is only for reporting purposes and doesn't alter processing behavior.
  • RoutingModel - Model for converting Check21 transactions into ACH.
    • ACHWithC21 - Will convert eligible Check transactions into ACH transactions
    • ACHOnly - Will convert all Check transactions into ACH transactions
    • C21Only - Will convert no Check transactions into ACH transactions
  • DefaultECC - ACH entry class that will be used for the routing model conversion

File Specific Details

  • AchCompanyName - This is what will appear on the bank statement of someone that is credited or debited by this merchant. If it isn't specified, this will fall back to ClientName.
  • DiscretionaryData - Merchant specific info to include in ACH files. Typically left blank.
  • NoOffsetFunding - ACH/ICL file setting. This flag will be determined by your ODFI (bank where your clearing account resides).
  • ContactPerson - Contact person for merchant or location. Required for POP entry class transactions.
  • ContactPhone - Contact phone for merchant or location. Required for POP entry class transactions.

Transaction Type Management

  • ValidEntryClassCodes - A list of allowed transaction types for the merchant or location. These correspond ACH entry classes and C21 for Check21.
  • TerminalCity - City this merchant is located in. Only required if POP transactions are in ValidEntryClassCodes.
  • TerminalState - Two letter state code for the state the merchant is located in. Only required if POP transactions are in ValidEntryClassCodes.

Transaction Limits

  • DailyFileLimit - The daily maximum number of batch files allowed to be uploaded
  • DailyLimit - The permitted total of all transactions for a single day. Once this limit is reached, transactions will be rejected.
  • DailySoftLimit - = If the daily transaction dollar total goes over this limit, a notification will be sent out to the contact email.
  • MonthlyFileLimit - The monthly maximum number of batch files allowed to be uploaded,
  • MonthlyLimit - The permitted total of all transactions for a single calendar month. Once this limit is reached, transactions will be rejected.
  • MonthlySoftLimit - If the monthly transaction dollar total goes over this limit, a notification will be sent out to the contact email.
  • TransactionLimit - The maximum allowed dollar amount for a single transaction.
  • TransactionSoftLimit - If a single transaction goes over this amount, a notification will be sent out to the contact email,
  • IsSuspectEnabled - If true enables a "Quarantine" feature for this merchant. Any transaction over the TransactionSoftLimit is placed into a quarantine area that requires manual approval for the transaction to be processed.

Clearing Account

  • UseClearingAccount - If this is true, ACHeck21 will manage disbursing funds from the ODFI clearing account to this merchant.
  • ReserveBalance - If the merchant has paid their reserve in advance, you should set the balance in dollars here.
  • ReserveRequirement - The minimum required balance of the merchant's reserve fund. If the reserve has been collected already, this number and the ReserveBalance should be the same. Otherwise, the reserve will be collected from their disbursements.
  • ReserveFundlingLevel - The percentage of each disbursement to collect towards ReserveBalance to meet ReserveRequirement. Typically this is 100%.
  • DisburseReleaseDays - The number of days to hold funds before disbursing to this merchant.
  • HoldFunds - If true, all disbursements to this merchant are put on hold until this flag is turned off.
    AggregateDisbursements - if false, when funds are disbursed, each batch will be it's own deposit. If true, all batches are combined into a single deposit.

Returned Item Handling

  • AutoRejectHandling - If true, returned items will be re-presented after optionally holding for a specified number of days.
  • RecoveryAccountId - Optional id of a merchant account where re-presented items will be deposited.
  • RejectHoldingDays - Number of days to hold a return before automatically re-presenting. Only applies if AutoRejectHandling is true.

Verification

  • RvdRuleSet - Ruleset id to use for transaction verification. This is configured separately.
  • UseSPS - if true, use fallback verification provider if there is an error with rvd.
  • RequirePreAuth - if true, requires transactions from this merchant to be approved by the verification service before being processed.

Updated over 5 years ago