MAmasspay
Business

Create business

Changed on

This POST endpoint is used to initiate create a business. <br> You can use this endpoint to establish a business which you can use to transact through the MassPay platform. <br> To use this endpoint, you need to provide the required parameters in the request Body, including business_legal_name, dba_business_name, business_incorporation_date, and other business entity related details. <br> The endpoint will then return a successful business token for the newly created entity. The response will contain a JSON object indicating the status of the request and any relevant business details. <br><br>Documents. Supporting documents (a KYB report, articles of incorporation, a proof of address, ...) can be sent along in documents, each Base-64 encoded; they are stored with the business and listed in the response. Since the whole request must stay under the 6 MB API limit, this suits a few small files: more, or larger, documents go through POST /business/{business_token}/documents once the business exists.

post/business

Request

Request body

reference_idstring required

Reference ID for the new Merchant (Business) being enrolled. Value is set by the integrator for their own correlation; MassPay does not currently persist or echo it back. It is not enforced to be unique and is not used for duplicate detection: re-using a reference_id does not return the previously created business. Duplicate detection is based on legal_name (compared case-insensitively, ignoring punctuation): a request whose legal name matches an existing business is rejected with 400 and the detail Business already exists. Only one instance is allowed per Legal Name. A request with a new legal name always creates a new business, even if the reference_id was used before. Persist the returned business_token as the durable identifier of the business.

legal_namestring required

Legal name of the business being enrolled.

type'Ccorp' | 'LLC' | 'Partnership' | 'Nonprofit' | 'Scorp' | 'Soleprop' | 'Other' required

The legal structure of the business. Options are "Ccorp", "LLC", "Partnership", "Nonprofit", "Scorp", "Soleprop", or "Other"

categorystring required

Category, or industry, the business operates within.

mcc_sicstring

The Merchant Category Code (MCC) or Standard Industrial Classfication (SIC) of the business.

countrystring required

The country where the business is domiciled. For United States, use "USA"

street1string required

The legal street one address of the business.

street2string

The legal street two address of the business.

citystring required

The legal address city of the business.

state_provstring required

The legal address state or province of the business.

postal_codestring required

The legal address zip, or postal code, of the business.

address_type'Residential' | 'Commercial' | 'Other'

The type of business address submitted.

place_of_incorporationstring required

The place where the business was incorporated. State, province and country

incorporation_datestring date required

The date of business incorporation. Formatted as, "YYYY-MM-DD"

phone_numberstring required

The phone number of the business.

email_addressstring required

The email address of the business.

website_addressstring required

The business website address.

descriptionstring required

A description of the business and its goods and services sold.

tax_id_type'Passport' | 'National Identification Card' | 'Driving License' | 'Social Security Card/Number' | 'Tax Payer Identification Card/Number' | 'Senior Citizen Identification Card' | 'Birth Certificate' | 'Village Elder Identification Card' | 'Permanent Residency Identification Card' | 'Alien Registration Certificate/Card' | 'PAN Card' | 'Voter’s Identification Card' | 'Health Insurance Card/Number' | 'Employer Identification Card' | 'Others not listed' required

The Tax ID type submitted.

tax_id_numberstring required

The Tax ID number of the business.

registration_numberstring required

The business registration number.

articles_of_incorporationstring

A Base-64 file of the articles of incorporation. Kept for existing integrations: prefer a documents entry of type articles_of_incorporation, which also carries the file name. A file sent here is stored as such a document (its type detected from its bytes) and listed in the response's documents.

partner_commentsstring

Any additional information to pass to our underwriting team.

notify_userboolean

Whenever set to true, we send an email to the Control person with the credentials to access the MassPay Dashboard. When set to false, no email notification would be sent.

partner_pays_transaction_feesboolean

Determines who is responsible for transaction fees incurred by this business. When set to true, the partner (the entity enrolling this business) assumes responsibility and will be billed for all transaction fees generated by this business's activity. When set to false, the business is responsible for paying its own transaction fees.

Example request

{
  "reference_id": "ref-apple-inc",
  "legal_name": "Apple Inc.",
  "type": "Ccorp",
  "category": "COMPUTER SOFTWARE STORE",
  "mcc_sic": "5744",
  "country": "USA",
  "street1": "One Apple Park Way",
  "city": "Cupertino",
  "state_prov": "CA",
  "postal_code": "95014",
  "address_type": "Commercial",
  "place_of_incorporation": "California",
  "incorporation_date": "1977-01-03",
  "phone_number": "4089961010",
  "email_address": "support@apple.com",
  "website_address": "https://www.apple.com",
  "description": "Consumer electronics",
  "tax_id_type": "Employer Identification Card",
  "tax_id_number": "94-2404110",
  "registration_number": "RA000598",
  "articles_of_incorporation": "MA==",
  "partner_comments": "Public company, ticker: NASDAQ: AAPL",
  "bank_details": {
    "name_on_account": "Apple Inc",
    "account_type": "Checking",
    "routing_number": "322271627",
    "account_number": "971121121"
  },
  "details": {
    "card_acceptance_card_present": 50
  },
  "principal": [
    {
      "type": [
        "Control Person"
      ],
      "reference_id": "ref-tim",
      "title": "CEO",
      "first_name": "Tim",
      "last_name": "Cook",
      "percentage_of_ownership": 0.02,
      "street1": "One Apple Park Way",
      "city": "Cupertino",
      "state_prov": "CA",
      "postal_code": "95014",
      "country": "USA",
      "email_address": "tcook@apple.com",
      "phone_number": "4089961010",
      "dob": "1960-11-01",
      "tax_id_type": "Driving License",
      "tax_id_number": "D123456789",
      "country_of_citizenship": "USA"
    }
  ],
  "documents": [
    {
      "document_type": "kyb_report",
      "file_name": "kyb-report-apple-inc.pdf",
      "file_content": "JVBERi0xLjQK...",
      "description": "KYB report from Middesk, run 2026-10-01"
    }
  ]
}

Response

Business enrollment request received successfully

business_tokenstring required

Token representing the business

api_keystring required

Bearer token for the new business's API access. It becomes valid a few seconds after this response, not instantly, in rare cases a few minutes. Until then, requests made with the key fail with 403 Forbidden and the body {"message":"Forbidden"}. Retry with a short backoff for up to a minute before treating a 403 as a permissions problem. Store the key now: it is not returned again.

Example response

{
  "documents": [
    {
      "document_token": "doc_8c5f1d2a-7b3e-4f9a-a1c6-3e2d9b8f7a10",
      "document_type": "kyb_report",
      "file_name": "kyb-report-apple-inc.pdf",
      "size_bytes": 184322,
      "description": "KYB report from Middesk, run 2026-10-01",
      "time_uploaded": "2026-10-21T18:42:07"
    }
  ]
}

Changes

  • f9fa41b7c45cRevision changes
    • warning

      added the new avs.completed enum value to the /// response property for the response status

    • warning

      added the new file_upload_req.created enum value to the /// response property for the response status

    • warning

      added the new file_upload_req.status enum value to the /// response property for the response status

    • warning

      added the new file_upload_req.verified enum value to the /// response property for the response status

    • warning

      added the new payin_deposit.return_completed enum value to the /// response property for the response status

    • warning

      added the new payin_deposit.returned enum value to the /// response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new avs.completed enum value to the request property ///

    • info

      added the new file_upload_req.created enum value to the request property ///

    • info

      added the new file_upload_req.status enum value to the request property ///

    • info

      added the new file_upload_req.verified enum value to the request property ///

    • info

      added the new payin_deposit.return_completed enum value to the request property ///

    • info

      added the new payin_deposit.returned enum value to the request property ///

    • info

      added the optional property to the response with the status