MerchantE API Docs
POST/services/apexrest/merchant-application-payfac/
Download OpenAPI (this endpoint)JSON|Download OpenAPI (generated)JSON

Create or Update Sub-Merchant Application

Create a new sub-merchant application or update an existing one. Both create and update operations use POST method.

For Create Operations:

  • Omit the Id field from Opp and Mer objects
  • All required fields must be provided
  • At least one Primary Contact/Beneficial Owner must be identified

For Update Operations:

  • Include the Id field (Opportunity SFID) in the Opp object
  • Include the Id field (Account SFID) in the Mer object
  • Source ID can be used to relate SFID to corresponding fields
  • Updates to applications in "Pending Underwriting" or "Closed Won" stages are NOT allowed

Important Guidelines:

  • Contact/Beneficial Owner fields required based on Legal Entity Type/Ownership
  • Set Is_ME_Underwriting__c to indicate underwriting type:
    • true: MerchantE is underwriting (PayFac-as-a-Service)
    • false: External underwriter (Wholesale PayFac)

Data Sections:

  • Merchant Information (Mer)
  • Checking Account (lstbussCheckAcc - can have multiple with different DDA Types)
  • Beneficial Owners (lstContact)
  • Transaction Payment Options (Opp)

Validation Notes:

  • Phone numbers must be 10 digits or (999) 999-9999 format
  • ZIP codes must be 5 digits
  • Federal Tax ID must be 9 digits
  • SSN must be 9 digits
  • Transit Routing Number must be 9 digits

Note: The host may be different for each organization. Use instance_url from Authorization Token response.

Request Body

Content type: application/json

Required3 fields

Core application components - Opportunity details, Merchant information, and at least one Beneficial Owner/Contact

Oppobject
Merobject
Merchant Information object. Contains demographic information about the merchant.
**Required fields for both Wholesale PayFac (WP) and PayFac-as-a-Service (PaaS).**
lstContactarray<object>
List of beneficial owners and contacts
Recommended1 field

Business checking account information for deposit processing

lstbussCheckAccarray<object>
List of business checking accounts (supports multiple accounts with different DDA types)
Enums (4)
Opp.attributes.type
Opportunity
Mer.attributes.type
Account
Mer.Ownership
Sole Proprietorship, Partnership, Limited Liability Company, Privately Held Corporation, Tax Exempt, Government, Publicly Traded Corporation, Financial Institution
Mer.Sponsorship__c
KeyBank, Synovus, Fresno First
Validations (32)
Opp.Id
pattern=^[a-zA-Z0-9]{15,18}$
Opp.High_Monthly_Volume__c
format=double · minimum=0
Opp.Avg_Ticket__c
format=double
Opp.High_Ticket__c
format=double · minimum=0
Opp.Visa_MC_Discover_Volume__c
format=double · minimum=0
Opp.Days_to_Ship_Deliver__c
maxLength=255
Opp.Refund_Policy__c
maxLength=255
Mer.Id
pattern=^[a-zA-Z0-9]{15,18}$
Mer.Association_ID_API_Field__c
maxLength=10
Mer.Legal_Name__c
minLength=1 · maxLength=100
Mer.Tax_ID__c
pattern=^\d{9}$ · maxLength=16
Mer.Name
minLength=1 · maxLength=255
Mer.BillingStreet
maxLength=255
Mer.BillingCity
maxLength=40
Mer.BillingState
maxLength=80
Mer.BillingPostalCode
pattern=^\d{5}$ · maxLength=20
Mer.BillingCountry
maxLength=80
Mer.Phone
pattern=^(\d{10}|\(\d{3}\) \d{3}-\d{4})$
Mer.App_Email__c
format=email · maxLength=100
Mer.Website
format=uri · maxLength=255
Mer.Customer_Service_Phone__c
pattern=^(\d{10}|\(\d{3}\) \d{3}-\d{4})$
Mer.Industry
maxLength=255
Mer.Industry_other__c
maxLength=100
Mer.Location_Type__c
maxLength=255
Mer.Location_Other__c
maxLength=255
Mer.Years_at_Location__c
maxLength=4
Mer.Date_Established__c
format=date
Mer.Chain_Non_Chain__c
maxLength=255
Mer.Description
maxLength=32000
Mer.MCC_API_Field__c
maxLength=100
Mer.BET_Table_ID_API_Field__c
maxLength=255
Mer.Association_ID__c
maxLength=18

Business Rules

  • At least one Primary Contact/Beneficial Owner must be identified
  • Only one Control Prong is allowed per application
  • Only one Authorized Signer is allowed per application
  • Maximum 4 Principals are allowed per application
  • Principals must have at least 25% ownership
  • Sum of % Ownership for all Principals must not exceed 100%
  • Phone numbers must be 10 digits or (999) 999-9999 format
  • ZIP codes must be 5 digits
  • Federal Tax ID must be 9 digits
  • SSN must be 9 digits
  • Transit Routing Number must be 9 digits

Entity-Specific Requirements

  • Sole Proprietorship: Only 1 Principal allowed
  • Partnership/LLC/Private Corp: Any 25%+ owners + 1 Control Prong
  • Tax Exempt/Government/Public Corp/Financial Institution: 1 Control Prong only

Create vs Update

  • Create: Omit the Id field from Opp and Mer objects
  • Update: Include the Id field (Opportunity SFID) in the Opp object
  • Update: Include the Id field (Account SFID) in the Mer object
  • Updates to applications in "Pending Underwriting" or "Closed Won" stages are NOT allowed
  • Source ID can be used to relate SFID to corresponding fields

Code samples

Copy-paste ready code in your preferred language.

API call

Copy/paste friendly
curl -X POST "https://merchante-solutions--cert.my.salesforce.com/services/apexrest/merchant-application-payfac/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "Opp": {
    "attributes": {
      "type": "Opportunity"
    },
    "Is_ME_Underwriting__c": true
  },
  "Mer": {
    "attributes": {
      "type": "Account"
    },
    "Association_ID_API_Field__c": "3941803045",
    "Legal_Name__c": "Acme Corporation LLC",
    "Tax_ID__c": "123456789",
    "State_of_Entity_Formation_Incorporation__c": "CA",
    "Name": "Acme Corp",
    "BillingStreet": "123 Main Street",
    "BillingCity": "San Francisco",
    "BillingState": "California",
    "BillingPostalCode": "94105",
    "BillingCountry": "United States",
    "Phone": "(415) 555-1234",
    "App_Email__c": "contact@acmecorp.com",
    "Website": "www.acmecorp.com",
    "Customer_Service_Phone__c": "888-555-1234",
    "Industry": "Retail",
    "Location_Type__c": "Ecommerce",
    "Ownership": "Limited Liability Company",
    "Years_at_Location__c": 3,
    "Date_Established__c": "2020-01-15",
    "Chain_Non_Chain__c": "Single Outlet",
    "Description": "Online retailer specializing in eco-friendly products",
    "MCC_API_Field__c": "5045",
    "Ever_accepted_credit_cards_before__c": true,
    "Ever_had_a_merchant_account_canceled__c": false
  },
  "lstbussCheckAcc": [
    {
      "attributes": {
        "type": "Business_Checking_Account__c"
      },
      "Bank_Name__c": "Wells Fargo",
      "Bank_Street_Address__c": "100 Market Street",
      "Bank_City__c": "San Francisco",
      "Bank_State__c": "CA",
      "Bank_Zipcode__c": "94105",
      "Checking_Account__c": "1234567890",
      "Transit_Routing__c": "121000248",
      "Years_Open__c": 5,
      "DDA_Type__c": "Deposit"
    }
  ],
  "lstContact": [
    {
      "attributes": {
        "type": "Contact"
      },
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "john.smith@acmecorp.com",
      "Date_of_Birth__c": "1975-06-15",
      "MailingStreet": "456 Oak Avenue",
      "MailingCity": "San Francisco",
      "MailingStateCode": "CA",
      "MailingPostalCode": "94102",
      "SSN__c": "123456789",
      "Contact_Role__c": "Principal;Control Prong",
      "Percentage_Owned__c": 100,
      "Title": "CEO"
    }
  ]
}'