Create an account

To create an account, you will POST a JSON Account Object to the /accounts endpoint. In the header of your request, you must supply a valid authentication token (that you retrieved from the /auth endpoint – see Authenticating to the API). The attributes that are required in the Account Object will depend on factors such as the merchant’s legal entity type and number of owners, as explained in The Account Object below.

https://api.gravitypayments.com/{version}/accounts

Content-Type: application/json
Authorization: Bearer {your authorization token goes here}

This is an example of a request body containing an Account Object with sample data. All the attributes of the Account Object are validated for type and content according to the entity being submitted. Individual attributes and their constraints are detailed below in The Account Object.

Responses will come in the form of a JSON object with success and message attributes. If success is false—that is, the request to create an account was unsuccessful—the message attribute will contain the relevant error message indicating what caused the failure.

Success responses will additionally contain an appId attribute. This number will then be used in webhook notifications to reference the submitted account, and therefore should be stored in your database.

string   required

Your API Key. This identifies that the new merchant is to be assigned under you.

hash   required

A hash of attributes pertaining to the merchant’s business location. Child attributes are:

dba

string   required

“Doing business as”, the merchant’s business name, trade name, or operating name.

type

string   required

The primary type of the business conducted by the merchant, as an industry designation. For a list of values pertaining to your clientele, please contact your Gravity Payments representative.

goodsAndServices

string   max. 255 characters   required

A brief description of the goods and services sold by the business. If relevant, include how payments are collected, for instance recurring charges or invoice terms. For nonprofits receiving donations, indicate any goods/services sold as fundraisers, as well as any specific deliverables expected from funding.

address

hash   required

A hash of the address of the business location (where customers make transactions). Child attributes are:

line1

string   max. 24 characters   required

The first line of the street address.

line2

string   max. 24 characters

The second line of the street address, if any.

city

string   max. 18 characters   required

The city where the business is located.

state

string   required

The state where the business is located.

postalCode

string   required

The zip or postal code of the business.

phone

string   required

The customer service phone number of the business. May be formatted with or without punctuation (dashes, parentheses, etc.).

email

string   required

The customer service email address of the business.

websiteUrl

string

The primary web address of the business, if any.

hash   required

A hash of the merchant’s legal entity information. Child attributes are:

type

string   required

The legal entity type. Valid values are:

• Sole Proprietorship
• Public Corp
• Private Corp
• Publicly Traded Partnership
• Private Partnership
• Publicly Traded LLC
• Private LLC
• Association/Estate/Trust
• Tax-Exempt Organization
• International/Organization
• Government

name

string   conditionally required

The legal name of the business entity. Required for all entity types except Sole Proprietorship.

tin

integer   9 digits   conditionally required

The Tax Identification Number (TIN/EIN) of the business). Required for all entity types except Sole Proprietorship.

address

hash   conditionally required

A hash of the legal address of the business entity. Required for all entity types except Sole Proprietorship. For child attributes, see Business Address.

yearsInBusiness

integer   required

The number of years that the merchant has been in business formed as this legal entity.

foreign

boolean   required

Is the legal entity of United States origin, or is it foreign? true if foreign, otherwise false. For Sole Proprietorships, if the owner is not a legal citizen of the United States, then true, otherwise false.

list   required

An array of owners of the business. For all entity types, at least one owner must be listed. For Private Corp, Private LLC, and Private Partnership, the total of all listed owners’ ownership percentage must be at least 50%. The first owner listed will be Signer 1. If a second owner is listed, they will be Signer 2. Any additional owners that are listed will not sign.

Attributes of each owner object are:

salutation

string

The owner’s salutation. Typical values are Mr., Mrs., Ms., Mx., Dr., and Prof.

firstName

string   required

The owner’s first name.

middleName

string

The owner’s middle name.

lastName

string   required

The owner’s last name.

title

string

The owner’s title. Valid values are: President, Vice President, Treasurer, Owner, Partner, CEO, Secretary, Director.

percentOwnership

integer   conditionally required

The ownership percentage of the owner, rounded to the nearest whole number. Required for all owners of a Private Corp, Private LLC, or Private Partnership.

ssn

string   9 numeric characters   required

The owner’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN).

dob

string   required

The owner’s date of birth, formatted as YYYY-MM-DD.

address

hash   required

A hash containing the owner’s address details. For child attributes, see Business Address.

phone

string   required

The owner’s phone number. May be formatted with or without punctuation (dashes, parentheses, etc.).

email

string   required

The owner’s email address.

hash   required

A hash of the business bank account information. The bank account specified here will be the account on record for depositing all funds and retrieving all fees. Child attributes are:

depositAccount

string   required

The account number of the business’s bank account.

depositRouting

string   required

The routing number of the business’s bank account.

hash

A hash of the designated account contact, if any. This entire hash is optional. If you are not supplying a contact in any given account, the contact key can simply be omitted from the request (rather than populating it with an empty hash as the value).

Child attributes are:

salutation

string

The contact’s salutation. Typical values are Mr., Mrs., Ms., Mx., Dr., and Prof.

firstName

string   conditionally required

The contact’s first name. Only required if supplying a contact.

middleName

string

The contact’s middle name.

lastName

string   conditionally required

The contact’s last name. Only required if supplying a contact.

title

string

The contact’s title.

address

hash

A hash containing the contact’s address details. For child attributes, see Business Address.

phone

string   conditionally required

The contact’s phone number. May be formatted with or without punctuation (dashes, parentheses, etc.). If supplying a contact, the contact must have a phone number or an email address, or both.

email

string   conditionally required

The contact’s email address. If supplying a contact, the contact must have an email address or a phone number, or both.

authorizedSigner

boolean

Is the contact authorized to sign for account changes on behalf of the business? true if yes, false if no. Defaults to false.

hash   required

A hash containing details of the merchant’s processing patterns. Child attributes are:

averageMonthlyCardVolume

integer   required

The average monthly total dollar amount of sales that the merchant is paid by card, as a whole number.

averageTicket

integer   required

The average dollar amount of a sale at the merchant’s business, as a whole number.

averageMonthlySalesVolume

integer

The average monthly total dollar amount of all sales by any payment method, as a whole number.

currentlyAcceptingCards

boolean   required

Is the business currently accepting credit/debit cards for payment? true if yes, false if no or new business.

seasonal

boolean

Is this a seasonal business, where sales are significantly higher during certain seasons than others? true if yes, false if no. Defaults to false.

seasonalFrom

integer   conditionally required

The month when the merchant’s high sales season begins, as a number (1-12). Only required if seasonal is true.

seasonalTo

integer   conditionally required

The month when the merchant’s high sales season ends, as a number (1-12). Only required if seasonal is true.

acceptanceMethods

hash   required

A hash of the card acceptance method percentages for the business. Percentage figures from the child attributes must add up to 100. If business is new, figures should represent estimates of expected activity. Child attributes are:

swiped

integer

The percentage of card sales that are accepted in person, where the card is physically swiped, tapped, or dipped with a reader. Round to the nearest whole number.

keyed

integer

The percentage of card sales that are manually key-entered, where the card numbers are typed into a computer or machine to charge a sale. Round to the nearest whole number.

moto

integer

The percentage of card sales that are accepted by mail or telephone order (MOTO), where the card is not present at the time of sale. Round to the nearest whole number.

internet

integer

The percentage of card sales that are accepted by online order from the cardholder. Round to the nearest whole number.

string

The code for the pricing to be assigned to this account. Defaults to “DEFAULT”. For more information, see Pricing Codes.

list

A list of product objects to order for deployment with this new account. For more information, see Products.

Attributes of each product object are:

code

string   conditionally required

The product code.

qty

integer   conditionally required

The quantity of the product to be ordered.

purchase

boolean

Is this product for purchase or rental by the merchant? true if purchase, false if rental or N/A. Defaults to false.

At the time of your enrollment, a default pricing arrangement will be set for accounts that you board through the Account API. The account pricing determines what a merchant will pay in transaction and account fees. The default arrangement is given the pricing code “DEFAULT”, which can be specified in the Account Object.

If you want to set custom pricing per account, we are more than happy to work with you to get that as the preferred pricing code, please reach out to an Integration Specialist to learn more.

When used in production, pricing specified with pricing codes is subject to final review and approval by Gravity Payments.

In setting up your access to the Account API, your Gravity Payments representative will provide you with product codes for any products that you may need to order with new merchant accounts, as can be specified in the Account Object. This will typically include one or more payment gateway options, and any card readers, terminals, or other hardware that your merchants will use to process payments. When a product is ordered through the API, the merchant’s bank account is charged for the purchase or rental cost of the product as applicable.

Should you need product codes for any additional products, your Gravity Payments representative can supply them.